Skip to content

docs: establish baseline glossary and ADRs#62

Merged
Cannon07 merged 1 commit into
mainfrom
docs/baseline-glossary-and-adrs
May 17, 2026
Merged

docs: establish baseline glossary and ADRs#62
Cannon07 merged 1 commit into
mainfrom
docs/baseline-glossary-and-adrs

Conversation

@Cannon07
Copy link
Copy Markdown
Owner

@Cannon07 Cannon07 commented May 17, 2026

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 via defer_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.shcore-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:

Test plan

  • No code changed — verify CI still passes (docs-only diff).
  • CONTEXT.md cross-links resolve.
  • ADRs link correctly to CONTEXT.md and to each other where referenced.

🤖 Generated with Claude Code

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>
@Cannon07 Cannon07 merged commit 9322612 into main May 17, 2026
2 checks passed
@Cannon07 Cannon07 deleted the docs/baseline-glossary-and-adrs branch May 17, 2026 20:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant