first commit

autonomous-ai-agents/hermes-agent/references/hermes-update-autostash-triage.md

@@ -0,0 +1,76 @@
+# Hermes Update Autostash Triage
+
+`hermes update` auto-stashes local changes before pulling. These accumulate as `stash@{N}` with the naming pattern:
+
+```
+hermes-update-autostash-YYYYMMDD-HHMMSS
+```
+
+## Triage Workflow
+
+### Step 1: List all stashes
+
+```bash
+git stash list
+```
+
+### Step 2: Quick scan each stash — file types matter
+
+```bash
+git stash show stash@{N} --stat
+```
+
+**Lock-file-only stashes** (only `package.json`, `package-lock.json`, `ui-tui/package-lock.json`):
+- Usually npm dependency resolution artifacts (registry mirror switches, peer dependency reclassification)
+- Safe to drop: `git stash drop stash@{N}`
+
+**Source-code stashes** (`.py`, `.ts`, `.tsx` files changed):
+- Need detailed analysis — these may contain valuable local features
+
+### Step 3: For source-code stashes — compare against current code
+
+Don't just `git stash pop`. First check if the features were already merged upstream:
+
+```bash
+# Get the full diff
+git stash show -p stash@{N}
+
+# For each key feature, search current code:
+grep -n "feature_keyword" path/to/file.py
+```
+
+**Classification:**
+- ✅ Already in current code → safe to drop
+- ❌ Missing from current code → candidate for restoration
+
+### Step 4: Decision matrix
+
+| Stash type | Action |
+|------------|--------|
+| Lock files only | Drop immediately |
+| Source code, all features merged | Drop |
+| Source code, some features missing | Selective restore (cherry-pick specific hunks) or apply + resolve conflicts |
+| Source code, all features missing | `git stash apply stash@{N}` then test |
+
+### Pitfalls
+
+- **Don't blindly pop stashes on an active branch** — always `apply` first (preserves stash), test, then `drop` if good.
+- **Registry mirror changes in lock files** (npmmirror.com, mirrors.tencentyun.com) are local environment artifacts, not valuable code. Drop them.
+- **`peer: true` removal** in lock files = npm re-resolved peer deps as direct deps. Not meaningful.
+- **5+ day old stashes** with source changes are likely abandoned experiments. Check if the user still needs them before restoring.
+- **Merge conflicts** are common after 5+ days — upstream moves fast. Expect to resolve manually.
+
+### Restoring selectively
+
+If only some hunks from a stash are needed:
+
+```bash
+# Apply but don't drop
+git stash apply stash@{N}
+
+# Review conflicts
+git diff
+
+# Or use interactive checkout for specific files
+git checkout stash@{N} -- path/to/specific/file.py
+```