feat(tui): Phase 3 power features — Who, Search, Timeline, Trace, File History screens
Complete TUI Phase 3 implementation with all 5 power feature screens: - Who screen: 5 modes (expert/workload/reviews/active/overlap) with mode tabs, input bar, result rendering, and hint bar - Search screen: full-text search with result list and scoring display - Timeline screen: chronological event feed with time-relative display - Trace screen: file provenance chains with expand/collapse, rename tracking, and linked issues/discussions - File History screen: per-file MR timeline with rename chain display and discussion snippets Also includes: - Command palette overlay (fuzzy search) - Bootstrap screen (initial sync flow) - Action layer split from monolithic action.rs to per-screen modules - Entity and render cache infrastructure - Shared who_types module in core crate - All screens wired into view/mod.rs dispatch - 597 tests passing, clippy clean (pedantic + nursery), fmt clean
This commit is contained in:
teernisse
154
AGENTS.md
154
AGENTS.md
@@ -818,3 +818,157 @@ Parse: `file:line:col` → location | 💡 → how to fix | Exit 0/1 → pass/fa
|
||||
- ❌ Full scan per edit → ✅ Scope to file
|
||||
- ❌ Fix symptom (`if (x) { x.y }`) → ✅ Root cause (`x?.y`)
|
||||
````
|
||||
|
||||
<!-- BEGIN LIQUID MAIL (v:48d7b3fc) -->
|
||||
## Integrating Liquid Mail with Beads
|
||||
|
||||
**Beads** manages task status, priority, and dependencies (`br` CLI).
|
||||
**Liquid Mail** provides the shared log—progress, decisions, and context that survives sessions.
|
||||
|
||||
### Conventions
|
||||
|
||||
- **Single source of truth**: Beads owns task state; Liquid Mail owns conversation/decisions
|
||||
- **Shared identifiers**: Include the Beads issue ID in posts (e.g., `[lm-jht] Topic validation rules`)
|
||||
- **Decisions before action**: Post `DECISION:` messages before risky changes, not after
|
||||
- **Identity in user updates**: In every user-facing reply, include your window-name (derived from `LIQUID_MAIL_WINDOW_ID`) so humans can distinguish concurrent agents.
|
||||
|
||||
### Typical Flow
|
||||
|
||||
**1. Pick ready work (Beads)**
|
||||
```bash
|
||||
br ready # Find available work (no blockers)
|
||||
br show lm-jht # Review details
|
||||
br update lm-jht --status in_progress
|
||||
```
|
||||
|
||||
**2. Check context (Liquid Mail)**
|
||||
```bash
|
||||
liquid-mail notify # See what changed since last session
|
||||
liquid-mail query "lm-jht" # Find prior discussion on this issue
|
||||
```
|
||||
|
||||
**3. Work and log progress (topic required)**
|
||||
|
||||
The `--topic` flag is required for your first post. After that, the topic is pinned to your window.
|
||||
```bash
|
||||
liquid-mail post --topic auth-system "[lm-jht] START: Reviewing current topic id patterns"
|
||||
liquid-mail post "[lm-jht] FINDING: IDs like lm3189... are being used as topic names"
|
||||
liquid-mail post "[lm-jht] NEXT: Add validation + rename guidance"
|
||||
```
|
||||
|
||||
**4. Decisions before risky changes**
|
||||
```bash
|
||||
liquid-mail post --decision "[lm-jht] DECISION: Reject UUID-like topic names; require slugs"
|
||||
# Then implement
|
||||
```
|
||||
|
||||
### Decision Conflicts (Preflight)
|
||||
|
||||
When you post a decision (via `--decision` or a `DECISION:` line), Liquid Mail can preflight-check for conflicts with prior decisions **in the same topic**.
|
||||
|
||||
- If a conflict is detected, `liquid-mail post` fails with `DECISION_CONFLICT`.
|
||||
- Review prior decisions: `liquid-mail decisions --topic <topic>`.
|
||||
- If you intend to supersede the old decision, re-run with `--yes` and include what changed and why.
|
||||
|
||||
**5. Complete (Beads is authority)**
|
||||
```bash
|
||||
br close lm-jht # Mark complete in Beads
|
||||
liquid-mail post "[lm-jht] Completed: Topic validation shipped in 177267d"
|
||||
```
|
||||
|
||||
### Posting Format
|
||||
|
||||
- **Short** (5-15 lines, not walls of text)
|
||||
- **Prefixed** with ALL-CAPS tags: `FINDING:`, `DECISION:`, `QUESTION:`, `NEXT:`
|
||||
- **Include file paths** so others can jump in: `src/services/auth.ts:42`
|
||||
- **Include issue IDs** in brackets: `[lm-jht]`
|
||||
- **User-facing replies**: include `AGENT: <window-name>` near the top. Get it with `liquid-mail window name`.
|
||||
|
||||
### Topics (Required)
|
||||
|
||||
Liquid Mail organizes messages into **topics** (Honcho sessions). Topics are **soft boundaries**—search spans all topics by default.
|
||||
|
||||
**Rule:** `liquid-mail post` requires a topic:
|
||||
- Provide `--topic <name>`, OR
|
||||
- Post inside a window that already has a pinned topic.
|
||||
|
||||
Topic names must be:
|
||||
- 4–50 characters
|
||||
- lowercase letters/numbers with hyphens
|
||||
- start with a letter, end with a letter/number
|
||||
- no consecutive hyphens
|
||||
- not reserved (`all`, `new`, `help`, `merge`, `rename`, `list`)
|
||||
- not UUID-like (`lm<32-hex>` or standard UUIDs)
|
||||
|
||||
Good examples: `auth-system`, `db-system`, `dashboards`
|
||||
|
||||
Commands:
|
||||
|
||||
- **List topics (newest first)**: `liquid-mail topics`
|
||||
- **Find context across topics**: `liquid-mail query "auth"`, then pick a topic name
|
||||
- **Rename a topic (alias)**: `liquid-mail topic rename <old> <new>`
|
||||
- **Merge two topics into a new one**: `liquid-mail topic merge <A> <B> --into <C>`
|
||||
|
||||
Examples (component topic + Beads id in the subject):
|
||||
```bash
|
||||
liquid-mail post --topic auth-system "[lm-jht] START: Investigating token refresh failures"
|
||||
liquid-mail post --topic auth-system "[lm-jht] FINDING: refresh happens in middleware, not service layer"
|
||||
liquid-mail post --topic auth-system --decision "[lm-jht] DECISION: Move refresh logic into AuthService"
|
||||
|
||||
liquid-mail post --topic dashboards "[lm-1p5] START: Adding latency panel"
|
||||
```
|
||||
|
||||
### Context Refresh (Before New Work / After Redirects)
|
||||
|
||||
If you see redirect/merge messages, refresh context before acting:
|
||||
```bash
|
||||
liquid-mail notify
|
||||
liquid-mail window status --json
|
||||
liquid-mail summarize --topic <topic>
|
||||
liquid-mail decisions --topic <topic>
|
||||
```
|
||||
|
||||
If you discover a newer "canonical" topic (for example after a topic merge), switch to it explicitly:
|
||||
```bash
|
||||
liquid-mail post --topic <new-topic> "[lm-xxxx] CONTEXT: Switching topics (rename/merge)"
|
||||
```
|
||||
|
||||
### Live Updates (Polling)
|
||||
|
||||
Liquid Mail is pull-based by default (you run `notify`). For near-real-time updates:
|
||||
```bash
|
||||
liquid-mail watch --topic <topic> # watch a topic
|
||||
liquid-mail watch # or watch your pinned topic
|
||||
```
|
||||
|
||||
### Mapping Cheat-Sheet
|
||||
|
||||
| Concept | In Beads | In Liquid Mail |
|
||||
|---------|----------|----------------|
|
||||
| Work item | `lm-jht` (issue ID) | Include `[lm-jht]` in posts |
|
||||
| Workstream | — | `--topic auth-system` |
|
||||
| Subject prefix | — | `[lm-jht] ...` |
|
||||
| Commit message | Include `lm-jht` | — |
|
||||
| Status | `br update --status` | Post progress messages |
|
||||
|
||||
### Pitfalls
|
||||
|
||||
- **Don't manage tasks in Liquid Mail**—Beads is the single task queue
|
||||
- **Always include `lm-xxx`** in posts to avoid ID drift across tools
|
||||
- **Don't dump logs**—keep posts short and structured
|
||||
|
||||
### Quick Reference
|
||||
|
||||
| Need | Command |
|
||||
|------|---------|
|
||||
| What changed? | `liquid-mail notify` |
|
||||
| Log progress | `liquid-mail post "[lm-xxx] ..."` |
|
||||
| Before risky change | `liquid-mail post --decision "[lm-xxx] DECISION: ..."` |
|
||||
| Find history | `liquid-mail query "search term"` |
|
||||
| Prior decisions | `liquid-mail decisions --topic <topic>` |
|
||||
| Show config | `liquid-mail config` |
|
||||
| List topics | `liquid-mail topics` |
|
||||
| Rename topic | `liquid-mail topic rename <old> <new>` |
|
||||
| Merge topics | `liquid-mail topic merge <A> <B> --into <C>` |
|
||||
| Polling watch | `liquid-mail watch [--topic <topic>]` |
|
||||
<!-- END LIQUID MAIL -->
|
||||
|
||||
Reference in New Issue
Block a user