docs: establish baseline glossary and ADRs#62
Merged
Conversation
Captures the domain vocabulary and architectural decisions for code-preview.nvim ahead of the bash-to-Lua migration in #47 phase 3. - CONTEXT.md — 17 terms across the diff-preview pipeline (agent, integration, proposal, preview, RPC, socket discovery, pidfile, hook entry, core handler, dispatcher, change/status/origin prefix/indicator, tier 1/2, source/file/ display path, visible-only mode, review gate, layout, renderer, reveal, hook context query, headless worker, in-process vs headless Lua). - ADR-0001 — Bash proposals are indicator-only, with origin-prefixed statuses. - ADR-0002 — Default to forcing the Claude Code review gate. - ADR-0003 — The inline renderer is the strategic direction; side-by-side is legacy at a feature floor. - ADR-0004 — Config lives only in Neovim; the bash layer holds none of its own. - AGENTS.md + docs/agents/ — pointers so future agent sessions read these docs. Follow-up cleanup tracked separately in #55, #56, #57, #58, #59, #60, #61. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Baseline domain vocabulary and architectural decisions, established via a grilling session ahead of the bash-to-Lua migration in #47 phase 3. Pure documentation — no behaviour change.
CONTEXT.md— 17 terms covering the full diff-preview pipeline: agent / integration, proposal / preview, RPC / socket discovery / pidfile, hook entry / core handler / dispatcher, change / status / origin prefix / indicator, tier 1 / tier 2, source/file/display path, visible-only mode / review gate, layout / renderer / reveal, hook context query, headless worker / in-process vs headless Lua.docs/adr/0001-origin-prefixed-status-values.md— Bash proposals are indicator-only, with origin-prefixed statuses. Records both the agent-behaviour observation (GPT-class models in Codex route edits through Bash) and the concurrency-safe prefix convention.docs/adr/0002-default-force-review-gate.md— Default to forcing the Claude Code review gate; opt-out viadefer_claude_permissions.docs/adr/0003-inline-renderer-as-future-default.md— The inline renderer is the strategic direction; side-by-side reaches feature-floor parity then closes for further additions.docs/adr/0004-config-lives-only-in-neovim.md— Config lives only in the running Neovim; the bash layer queries on demand via hook context query.AGENTS.md+docs/agents/— pointers so future AI agent sessions discover the canonical issue tracker, triage labels, and domain doc layout.Why now
#47 phase 3 (port
core-pre-tool.sh→core-pre-tool.lua) will reshape multiple modules. Doing it on a foundation of settled vocabulary makes the diff easier to review and the discussions easier to ground.Follow-ups
Refactor opportunities surfaced while preparing the baseline, tracked separately so they don't pollute either this PR or the phase 3 work:
show_diff(source path / file path / display path)diff.lua(mark_change_and_reveal)is_installed/install_state)ClaudePreview*command aliases/tmp/claude-diff-*tempfiles to/tmp/code-preview-*lua/code-preview/diff.luainto focused modulesTest plan
CONTEXT.mdcross-links resolve.CONTEXT.mdand to each other where referenced.🤖 Generated with Claude Code