From e2d0ff03529b0a34146dbd97c3ebbb2b2f6d1faa Mon Sep 17 00:00:00 2001
From: Otto <otto@openclaw.local>
Date: Sat, 7 Mar 2026 17:14:58 +0100
Subject: [PATCH] Add unification plan for git hooks

---
 UNIFICATION_PLAN.md | 189 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 189 insertions(+)
 create mode 100644 UNIFICATION_PLAN.md

diff --git a/UNIFICATION_PLAN.md b/UNIFICATION_PLAN.md
new file mode 100644
index 0000000..334eae7
--- /dev/null
+++ b/UNIFICATION_PLAN.md
@@ -0,0 +1,189 @@
+# Git Hooks Unification Plan
+
+## Goal
+
+Consolidate the current multi-script architecture into standard, self-contained git hook files that can be installed directly without external dependencies.
+
+## Current Architecture
+
+```
+scripts/
+├── generate-proof.sh      # Core proof generation logic
+├── backfill-proofs.sh     # History scanning + upgrade
+├── install-ots-hook.sh    # Installer script
+├── pre-commit-backfill    # Pre-commit hook wrapper
+├── check-attestation.sh   # Status checker
+└── setup-gitignore.sh     # Gitignore helper
+```
+
+**Problems:**
+- Hooks depend on external scripts in repo root or global paths
+- Multiple files to manage and copy
+- Path resolution logic is fragile
+- Hard to install manually
+
+## Target Architecture
+
+```
+hooks/
+├── post-commit        # Self-contained post-commit hook
+├── pre-commit         # Self-contained pre-commit backfill hook
+└── install.sh         # Simple installer (copies hooks)
+```
+
+Each hook file contains all necessary logic inline - no external dependencies.
+
+## Implementation Plan
+
+### Phase 1: Create Self-Contained Hooks
+
+#### `hooks/post-commit`
+
+Inline the entire `generate-proof.sh` logic:
+
+```bash
+#!/bin/bash
+# Self-contained post-commit hook
+
+set -e
+
+COMMIT_HASH=$(git rev-parse HEAD)
+OUTPUT_FILE=".ots/proof.ots"
+mkdir -p "$(dirname "$OUTPUT_FILE")"
+
+# Inline: generate_with_ots_cli()
+temp_file=$(mktemp)
+temp_ots="${temp_file}.ots"
+python3 -c "import sys; sys.stdout.buffer.write(bytes.fromhex('$COMMIT_HASH'))" > "$temp_file"
+ots stamp "$temp_file"
+if [ -f "$temp_ots" ]; then
+    mv "$temp_ots" "$OUTPUT_FILE"
+    rm -f "$temp_file"
+fi
+
+# Inline: get previous commit
+PREV_COMMIT=$(git rev-parse HEAD^1 2>/dev/null || echo "")
+if [ -n "$PREV_COMMIT" ]; then
+    echo "$PREV_COMMIT" > ".ots/prev-commit.txt"
+fi
+
+echo "[ots] Proof generated: ${COMMIT_HASH:0:8}"
+```
+
+#### `hooks/pre-commit`
+
+Inline the entire `backfill-proofs.sh` logic:
+
+```bash
+#!/bin/bash
+# Self-contained pre-commit backfill hook
+
+set -e
+
+# Inline: cache functions
+get_cached_status() { ... }
+cache_status() { ... }
+
+# Inline: main loop
+COMMITS=$(git rev-list --reverse HEAD)
+for COMMIT in $COMMITS; do
+    PROOF_FILE=".ots/${COMMIT}.ots"
+    if [ -f "$PROOF_FILE" ]; then
+        # Check cache, skip if attested
+        # Upgrade if pending and cache expired
+    else
+        # Generate proof inline
+    fi
+done
+```
+
+### Phase 2: Simplify Installer
+
+#### `hooks/install.sh`
+
+```bash
+#!/bin/bash
+# Simple installer - just copies hooks
+
+REPO_PATH="${1:-.}"
+HOOKS_DIR="$(cd "$REPO_PATH" && git rev-parse --git-dir)/hooks"
+
+echo "Installing OTS hooks to: $HOOKS_DIR"
+
+cp "$(dirname "$0")/post-commit" "$HOOKS_DIR/post-commit"
+cp "$(dirname "$0")/pre-commit" "$HOOKS_DIR/pre-commit"
+
+chmod +x "$HOOKS_DIR/post-commit" "$HOOKS_DIR/pre-commit"
+
+echo "✓ Hooks installed"
+```
+
+### Phase 3: Migration Path
+
+1. **Keep current scripts** in `scripts/` for backward compatibility
+2. **Add new `hooks/`** directory with unified hooks
+3. **Update SKILL.md** to recommend new hooks
+4. **Deprecate old scripts** (add deprecation warnings)
+5. **Eventually remove** old scripts in next major version
+
+## Benefits
+
+| Aspect | Before | After |
+|--------|--------|-------|
+| Files to install | 6 scripts | 2 hooks + installer |
+| External dependencies | Yes (scripts in root) | No (self-contained) |
+| Manual installation | Complex (path resolution) | Simple (copy 2 files) |
+| Debugging | Hard (multiple files) | Easy (single file per hook) |
+| Portability | Low (path-dependent) | High (drop-in) |
+
+## Trade-offs
+
+**Pros:**
+- Simpler installation
+- No path resolution logic
+- Easier to understand (single file = single responsibility)
+- Better for manual installation
+
+**Cons:**
+- Code duplication (generate-proof logic in both hooks)
+- Larger hook files (~200-300 lines each)
+- Harder to update (must update multiple files)
+
+## Mitigation
+
+- Extract shared functions into a sourced library: `hooks/.ots-lib.sh`
+- Hooks source the library: `source "$(dirname "$0")/.ots-lib.sh"`
+- Library is installed alongside hooks
+
+## Revised Architecture (with Library)
+
+```
+hooks/
+├── .ots-lib.sh      # Shared functions (generate_proof, check_attested, etc.)
+├── post-commit      # Sources library, calls generate_proof()
+├── pre-commit       # Sources library, calls backfill_history()
+└── install.sh       # Copies all files
+```
+
+## Next Steps
+
+1. [ ] Create `hooks/.ots-lib.sh` with extracted functions
+2. [ ] Create `hooks/post-commit` using library
+3. [ ] Create `hooks/pre-commit` using library
+4. [ ] Create `hooks/install.sh`
+5. [ ] Test on git-timestamps-test repo
+6. [ ] Update documentation
+7. [ ] Deprecate old `scripts/` directory
+
+## Timeline
+
+- Phase 1 (Library + Hooks): 1-2 hours
+- Phase 2 (Testing): 30 min
+- Phase 3 (Documentation): 30 min
+- **Total**: ~3 hours
+
+---
+
+**Branch**: `git-scripts`  
+**Created**: 2026-03-07  
+**Status**: Planning