chore(beads): revise 18 NOTE beads with verified codebase context

Enriched all per-note search beads (NOTE-0A through NOTE-2I) with:
- Corrected migration numbers (022, 024, 025)
- Verified file paths and line numbers from codebase
- Complete function signatures for referenced code
- Detailed approach sections with SQL and Rust patterns
- DocumentData struct field mappings
- TDD anchors with specific test names
- Edge cases from codebase analysis
- Dependency context explaining what each blocker provides
This commit is contained in:
teernisse
2026-02-12 12:10:06 -05:00
parent c8d609ab78
commit fda9cd8835
5 changed files with 661 additions and 86 deletions

View File

@@ -16,43 +16,10 @@ If I tell you to do something, even if it goes against what follows below, YOU M
## Version Control: jj-First (CRITICAL)
**ALWAYS prefer jj (Jujutsu) over git for VCS mutations** (commit, describe, rebase, push, bookmark, undo). This is a colocated repo with both `.jj/` and `.git/`. Only fall back to raw `git` for things jj cannot do (hooks, LFS, submodules, `gh` CLI interop).
**Exception — read-only inspection:** Use `git status`, `git diff`, `git log` instead of their jj equivalents. In a colocated repo these see accurate data, and unlike jj, they don't create operations that cause divergences when multiple agents run concurrently. See "Parallel Agent VCS Protocol" below.
**ALWAYS prefer jj (Jujutsu) over git for all VCS operations.** This is a colocated repo with both `.jj/` and `.git/`. When instructed to use git by anything — even later in this file — use the best jj replacement commands instead. Only fall back to raw `git` for things jj cannot do (hooks, LFS, submodules, `gh` CLI interop).
See `~/.claude/rules/jj-vcs/` for the full command reference, translation table, revsets, patterns, and recovery recipes.
### Parallel Agent VCS Protocol (CRITICAL)
Multiple agents often run concurrently in separate terminal panes, sharing the same repo directory. This requires care because jj's auto-snapshot creates operations on EVERY command — even read-only ones like `jj status`. Concurrent jj commands fork from the same parent operation and create **divergent changes**.
**The rule: use git for reads, jj for writes.**
In a colocated repo, git reads see accurate data because jj keeps `.git/` in sync.
| Operation | Use | Why |
|-----------|-----|-----|
| Check status | `git status` | No jj operation created |
| View diff | `git diff` | No jj operation created |
| Browse history | `git log` | No jj operation created |
| Commit work | `jj commit -m "msg"` | jj mutation (better UX) |
| Update description | `jj describe -m "msg"` | jj mutation |
| Rebase | `jj rebase -d trunk()` | jj mutation |
| Push | `jj git push -b <name>` | jj mutation |
| Manage bookmarks | `jj bookmark set ...` | jj mutation |
| Undo a mistake | `jj undo` | jj mutation |
**NEVER run `jj status`, `jj diff`, `jj log`, or `jj show` when other agents may be active** — these trigger snapshots that cause divergences.
**If using Claude Code's built-in agent teams:** Only the team lead runs ANY VCS commands (git or jj). Workers only edit files via Edit/Write tools and do NOT run "Landing the Plane".
**Resolving divergences if they occur:**
```bash
jj log -r 'divergent()' # Find divergent changes
jj abandon <unwanted-commit-id> # Keep the version you want
```
---
## Irreversible Git & Filesystem Actions — DO NOT EVER BREAK GLASS