tai/research/INDEX.md

# Research Archive Index

**Molodetz Institute — Research & Retrieval Division.** This is the living registry of every subject in `research/`. It is updated in the same pass as any new research, per the standing rule in [README.md](README.md#4-the-standing-rule-also-stated-in-agentsmd) §4. Never edit a subject's documents without also updating its row here.

## Global statistics

| Metric | Value |
|---|---|
| Subjects | 6 |
| Total source documents | 421 |
| — Tier 1 (Source Dossier, independently analyzed) | 111 |
| — Tier 2 (Source Citation Card, listed only) | 310 |
| Total conclusion documents | 8 |
| Archive opened | 2026-10-09 |
| Last updated | 2026-10-11 |

## Subjects

| Subject | Sources (T1 / T2) | Conclusions | Opened | Last updated | Driving task |
|---|---|---|---|---|---|
| [`sqlite-rag-hybrid-search`](sqlite-rag-hybrid-search/) | 32 (10 / 22) | 1 | 2026-10-09 | 2026-10-09 | Designing tmux-log export + chunked retrieval; settled on BM25-only, no vector DB |
| [`agent-memory-recency-tracking`](agent-memory-recency-tracking/) | 63 (16 / 47) | 1 | 2026-10-09 | 2026-10-09 | Designing an LRU-style last-used/use-count tracker for vault records and chunks |
| [`async-pty-process-testing`](async-pty-process-testing/) | 59 (20 / 39) | 1 | 2026-10-09 | 2026-10-09 | Designing tai_test.py (pty vs. pipes, non-blocking stdin, process-group cleanup, test-framework shape) — backfilled after it was initially skipped, see activity log |
| [`shell-multiplexer-auto-attach`](shell-multiplexer-auto-attach/) | 138 (48 / 90) | 2 | 2026-10-09 | 2026-10-10 | Designing a tai-managed terminal multiplexer + bashrc auto-attach: tmux-as-substrate recommendation, interactive-vs-automation shell detection; extended 2026-10-10 to cover zsh/fish hook syntax |
| [`tui-framework-design`](tui-framework-design/) | 55 (10 / 45) | 1 | 2026-10-10 | 2026-10-10 | Designing tai's in-house TUI framework (retained DOM, cuts/chops compositor, SGR mouse, bubbling events, VT sub-terminals); extended 2026-10-10 with synchronized-output verification (DEC 2026); implemented in working-tree tai.py and verified the same session; same-day follow-up fixed the 19 failures natively, deleted tai_pkg/, suite 320/320 green, committed; extended again for kitty keyboard protocol (double-Shift prompt dialog) |
| [`agentic-tool-loop-design`](agentic-tool-loop-design/) | 74 (7 / 67) | 2 | 2026-10-11 | 2026-10-11 | Fixing stop-after-narration on prompt-JSON CLI backends without intent regexes; decided structural loop control plus exactly-once JSON-contract repair plus prompt contract, implemented in tai.py the same session (suite 357/357 + 16/16 green); approval tiers judged already industry-standard, no change |

## Recent activity log

| Date | Subject | Event |
|---|---|---|
| 2026-10-09 | — | Archive created: specification (`README.md`), index (this file), and both subjects above backfilled from the day's research in full, per explicit instruction to retroactively capture every source consulted that day. |
| 2026-10-09 | `sqlite-rag-hybrid-search` | 32 sources (10 Tier 1 / 22 Tier 2) + 1 conclusion recorded (the conclusion: pure SQLite FTS5/BM25 chunked search, deliberately no embeddings/vector DB — see `conclusions/`). Counts verified directly against the written files, not taken from the authoring agent's self-report. |
| 2026-10-09 | — | Spec change: `Tier` split into its own standalone metadata row (`1` / `2` / `N/A`) instead of a parenthetical inside `Document type`, so it's directly filterable. All 97 existing documents across both subjects backfilled to match in the same pass; counts re-verified afterward (unchanged: 26 Tier 1, 69 Tier 2, 2 Conclusions). |
| 2026-10-09 | `agent-memory-recency-tracking` | 63 sources (16 Tier 1 / 47 Tier 2) + 1 conclusion recorded (the conclusion: `last_used`/`use_count` tracking proposal for records and chunks, throttled-write pattern, no eviction policy yet — see `conclusions/`). One source (`glama-code-index-mcp-bm25-hybrid.md`) was promoted from the originally-planned Tier 2 to Tier 1 by the authoring agent mid-task because it contained specific attributable numeric findings — exactly the judgment call §3 of `README.md` calls for, logged here rather than silently absorbed. Counts verified directly against the written files. |
| 2026-10-09 | `async-pty-process-testing` | New subject, opened as a correction: the eight `WebSearch` calls behind `tai_test.py`'s design (pty vs. pipes, non-blocking stdin, process-group cleanup, test-framework patterns) were initially skipped from the archive under the reasoning "informal engineering reference, not a design decision" — a silent, unilateral exception to the Research Rule, and wrong (see `README.md` §4's added "no exception, ever" paragraph). Backfilled: 59 sources (20 Tier 1 / 39 Tier 2) + 1 conclusion (`conclusions/tai-test-framework-design.md`). Counts verified directly against the written files via `research/audit.py`, not taken from the authoring agent's self-report alone. A `PostToolUse`/`WebSearch` hook (`.claude/settings.json`) was also added the same day specifically to stop this from recurring. |
| 2026-10-09 | `shell-multiplexer-auto-attach` | 71 sources (38 Tier 1 / 33 Tier 2) + 1 conclusion recorded (the conclusion: build on tmux as a substrate rather than a from-scratch multiplexer; reliable human-vs-automation shell detection has no single solution, only a combination of weaker signals plus a safety-file escape hatch). Counts verified directly against the written files via `research/audit.py`. Hook fired correctly for all 8 underlying WebSearch calls during this task. |
| 2026-10-10 | `shell-multiplexer-auto-attach` | Extended with 67 more sources (10 Tier 1 / 57 Tier 2) + 1 more conclusion (`conclusions/cross-shell-hook-syntax-bash-zsh-fish.md`), covering 7 WebSearch calls on zsh/fish command-not-found and plexer-hook syntax (fish_command_not_found, zsh command_not_found_handler, fish's isatty builtin vs. a missing `test -t`, `status is-interactive`/`is-login`, config.fish always being sourced, and the `fish -i` flag). Subject total now 138 sources (48 Tier 1 / 90 Tier 2), 2 conclusions. The research backed a same-session implementation (tai.py's `shell_rc_path`/`ZSH_NOTFOUND_BLOCK`/`FISH_NOTFOUND_BLOCK`/`FISH_PLEXER_BLOCK`/`op_zsh_hook`/`op_fish_hook`/`op_zsh_plexer_hook`/`op_fish_plexer_hook`, new tests in `test_tai.py` and `tests/bashrc.py`, and `zsh`/`fish` added to `tests/docker/Dockerfile`) rather than remaining a proposal. Counts verified directly against the written files via `research/audit.py` (PASS). |
| 2026-10-10 | `tui-framework-design` | New subject: 44 sources (7 Tier 1 / 37 Tier 2) + 1 conclusion (`conclusions/retained-dom-compositor-tui.md`), covering 4 WebSearch calls plus 7 direct page fetches on TUI architecture (Textual events/layout/animation guides, pyte repo, SGR mouse protocol, rabbitui Textual synthesis, tmux popup-removal commit). Decision: retained-DOM framework in tai.py with cuts/chops compositor, named layers, bubbling events, SGR mouse, tick animations, reimplemented VT sub-terminals. Nothing built yet; implementation plan presented, awaiting go. Counts hand-verified (shell unavailable for `research/audit.py` in this session). |
| 2026-10-10 | `tui-framework-design` | Extended with 10 more sources (2 Tier 1 / 8 Tier 2) verifying synchronized-output framing (DEC mode 2026, `CSI ? 2026 h/l`, harmless no-op where unsupported). Subject total now 54 sources (9 Tier 1 / 45 Tier 2), 1 conclusion. Implementation approved by retoor the same session; framework being built into tai.py. |
| 2026-10-10 | `tui-framework-design` | Implementation finished and verified (no new sources): framework in working-tree `tai.py`, `tui.md` docs, `/demo` + `--demo` + `--demo-shot` wiring, 49 TUI unit tests green, 21/21 headless interaction checks green, 10/10 live pty e2e checks green, `test_seal.py` green. The 19 remaining `test_tai.py` failures are the pre-existing monolith/facade working-tree mismatch, proven unrelated via stash comparison. Conclusion document updated. |
| 2026-10-10 | `tui-framework-design` | Follow-up (no new sources): the 19 failures from the previous row were fixed natively — five classes (`Consts`, `Install`, `Sandbox`, `Opencode`, `SysInfo`) defined directly in standalone `tai.py` with module functions delegating, four test patch-targets corrected to the real `tai.*` seams (assertions unchanged) — then `tai_pkg/` deleted outright per retoor's call. Suite now 320/320 green (`test_tai.py`) + 16/16 (`test_seal.py`); `tui.md` focus rules updated (Tab always cycles, auto-focus, focus memory); committed. Conclusion document forward-corrected. |
| 2026-10-10 | `tui-framework-design` | Extended with 1 more source (Tier 1: the kitty keyboard protocol specification, direct fetch) to settle double-Shift detection for a prompt dialog: bare modifier presses need flag 8, press is `57441;2u`, filter `:2`/`:3` via flag 2, push `CSI > 10 u` best-effort with no query round-trip, pop on teardown. Subject total now 55 sources (10 Tier 1 / 45 Tier 2), 1 conclusion. |
| 2026-10-11 | `agentic-tool-loop-design` | New subject: 74 sources (7 Tier 1 / 67 Tier 2) + 2 conclusions, covering 7 searches plus 7 direct fetches on agentic loop control (Anthropic stop_reason docs, Building Effective Agents, Agent SDK loop, Writing Tools for Agents, ReAct pattern, tool-calling playbook, small-model narration field report). Decisions: keep loop control structural (tool_calls presence is the stop_reason equivalent, never text parsing), repair a missing JSON envelope exactly once per CLI-backend call, harden the prompt contract, leave approval tiers unchanged. Backed a same-session implementation (tai.py `opencode_find_answer`/`cli_json_repair_prompt`/`cli_json_turn`, prompt-contract sentences, 7 new tests) with suite 357/357 + 16/16 green. Counts verified directly against the written files. |

## How to use this index

- Before starting new research, search this table for an existing subject before opening a new one (see [README.md](README.md#2-directory-layout) §2, "one subject, one home").
- Every subject folder is self-contained: its sources live flat inside it, its conclusions live in its `conclusions/` subfolder.
- Tier 1 vs Tier 2 is a statement about how deeply a source was actually read, not about its importance — see [README.md](README.md#3-the-three-document-types) §3 for the exact distinction.