boocode/docs/plans/post-review-backlog/artifacts/.discovery-notes.md

Discovery notes — post-review-backlog plan

Single source of truth for project context. Specialists: read this first, do NOT re-grep what is here. Search further only for what your domain needs that is not covered.

Tech stack

• Monorepo, pnpm workspaces: apps/server (BooChat — Fastify + postgres, native inference, read-only tools), apps/web (React + Vite SPA), apps/coder (BooCoder — host systemd service, write tools + external-agent dispatch, port 9502), apps/booterm (PTY/tmux). TypeScript strict, NodeNext (.js import suffixes) on server + coder.
• Tests: vitest (pinned ^3). server pnpm -C apps/server test; coder pnpm -C apps/coder test (globals:false — import describe/it/expect). Include glob src/**/__tests__/**/*.test.ts. No web test harness, no linters. DB-integration tests opt-in via DATABASE_URL + describe.runIf.
• Deploy: apps/coder → sudo systemctl restart boocoder; apps/web|server → docker compose up --build -d boocode.
• Postgres 16, DB boochat. Two schema files: apps/server/src/schema.sql (sessions/chats/messages/ message_parts) + apps/coder/src/schema.sql (agent_sessions, worktrees, pending_changes, available_agents, checkpoints, claude_session_entries, tasks extension).

ADRs / coding standards found

• No docs/adr/ directory. Architectural decisions live in boocode_roadmap.md (Decisions log) + per-app CLAUDE.md files (auto-loaded when editing that subtree) + openspec/changes/archived/.
• Coding standards: docs/coding-standards/ (canonical), surfaced via .claude/rules/coding-standards/ path-scoped index files. Not loaded automatically; open on demand.
• Cross-cutting conventions in root CLAUDE.md "Conventions" section (WS-frame parity, sentinels, JSONB via sql.json, event dedup discipline, deploy-by-surface).

Code touch points (per scope-brief item)

• F1 task-cancel: apps/coder/src/services/dispatcher.ts (private ac=new AbortController() at ~316/655/991/1248; inflight=Map<sessionId,Promise> at :56 — no per-task AbortController registry); apps/coder/src/routes/tasks.ts:110-148 (cancel route — inference.cancel + DB only); routes/messages.ts:388 (session stop); backends honor ctx.signal: pty-dispatch.ts:159 (child.kill), backends/warm-acp.ts:318 (session/cancel), backends/opencode-server.ts:775 (session.abort), backends/claude-sdk.ts:209 (interrupt). Frontend apps/web/src/components/panes/CoderPane.tsx:987 handleStop; api/client.ts:395 cancelTask.
• F2 parser prune: apps/server/src/services/inference/tool-call-parser.ts (exports extractToolCallBlocks, stripToolMarkup, parseXmlToolCall, parseInvokeToolCall, isPlaceholderArgValue, XML_/INVOKE_ consts). Live consumers: stream-phase.ts:263-284 (extractToolCallBlocks, text-delta fallback path), :285-294 (structured tool-call path — authoritative today), tool-phase.ts:122 + error-handler.ts:25,106 (stripToolMarkup). llama-swap native --jinja parsing confirmed ON (external host :8401).
• F3 xml logging: tool-call-parser.ts:65 console.debug; one call site in stream-phase.ts executeStreamPhase.
• F4 notify-hook: agent config paths ~/.claude/settings.json, ~/.qwen/settings.json, ~/.config/goose/; existing readers claude-command-discovery.ts:84, qwen-settings.ts, provider-registry.ts. Existing normalize helper apps/coder/src/services/normalize-agent-status.ts (normalizeAgentEvent). Existing status publish wired at dispatcher turn boundaries (v2.7.6); index.ts:86 references #10. permission-waiter.ts:47 has a PermissionHooks registry.
• F5 compaction surfacing: apps/coder/src/services/backends/opencode-server.ts SSE arm handling (~215-311 region); WS frame parity → server ws-frames.ts + web apps/web/src/api/types.ts (WsFrame).
• F6 resilience: apps/server/src/services/inference/stream-phase.ts:261 (for await ... result.fullStream), abort check at :333, usage at :343. Frontend 60s discard_stale watchdog is the only stall guard today.
• F7 session-history MCP tool: apps/coder/src/services/mcp-server.ts (existing BooCoder MCP tools); read path messages_with_parts view.
• F8 diff-line UX: diff UI component NOT located by git ls-files apps/web | grep -i diff (returned empty) — UX specialist must locate the actual diff/changes panel component (BOOCODER.md calls it "DiffPanel"; may be named differently or nested). Routes through dispatcher + AgentComposerBar.
• F9 retire :9502: apps/coder/web/ package + static serve in apps/coder/src/index.ts + coder build scripts/Dockerfile. KEEP WS + REST routes.

Recent activity / precedent

• HEAD e5ce01a (v2.7.11). v2.7.x line (relicense, write-edit-robustness, sampling-streamjson-tokens, mistake-tracker-ledger, claude-sdk-sessionstore, agent-status-normalize, UI batches) all shipped 2026-06-01.
• Pure-helper + TDD precedent for extraction: backends/turn-guard.ts, backends/lifecycle-decisions.ts, mistake-tracker.ts (pure module + unit test, then wire). F1/F2/F6 should follow it.
• Parallel-disjoint-file agent precedent: v2.7.0/v2.7.1/v2.7.3 each built by 3 parallel agents over disjoint files — relevant to decomposition/sequencing.

Enumerated gaps (searched, not found)

• No feature-specification.md — scope-brief.md is the ground-truth stand-in.
• No docs/adr/.
• Diff UI component filename not found via naive grep (F8) — needs UX specialist location.
• llama-swap config is NOT in-repo (external host :8401); native-jinja state confirmed by live probe only.
• F8 (diff-line UX) and F4 (notify-hook) are the two items most likely to need their own plan-a-feature; they have no behavioral spec beyond the review-doc pattern description.