diple/AGENTS.md

# AGENTS.md

## Protected README preamble

The notice at the very top of `README.md` stating that the entire repository is
AI-generated, including the adjacent placeholder for the repository owner's
personal comments, is intentional and permanent.

**Do not remove, replace, relocate, soften, or rewrite that preamble or its
owner-comment placeholder.** Only the repository owner may fill in or edit the
placeholder. Changes elsewhere in the README must preserve this section
verbatim and keep it before the project title.

## Repository purpose

`diple` is a keyboard-first terminal UI for people receiving GitHub pull
request reviews. It is a Go 1.24 application built with Bubble Tea and
Lip Gloss. It uses GitHub's GraphQL and REST APIs, authenticates through the
GitHub CLI or token environment variables, and keeps optional cache, draft,
read-state, and local-AI data on disk.

The module path is:

```text
git.pablu.de/Pablu/diple
```

The application is one `package main`. There is no internal package hierarchy,
so keep new code close to the feature it serves and avoid introducing
abstractions without a concrete second use.

## Product boundaries

- The primary user is the PR author or assignee responding to a review, not the
  reviewer submitting one.
- Reading must remain useful when some GitHub subsections fail or cached data
  is temporarily stale.
- Mutations must be explicit, permission-aware, confirmed where destructive,
  and protected against stale PR heads where applicable.
- Local AI findings and discussions are local-only. They must never be
  published to GitHub implicitly.
- AI providers must not receive local checkout contents. Current AI context
  comes from authenticated GitHub PR data and filtered diffs.
- Never run code, hooks, tools, or repository commands on behalf of an AI
  provider. Preserve the hardened, tool-free provider boundary.
- The UI is keyboard-first. Similar actions should use the same configurable
  keybinding groups across screens.
- Narrow terminals, wrapped content, Unicode grapheme clusters, no-color mode,
  and high-contrast mode are supported behavior, not optional polish.

## Important files

- `main.go`: startup, configuration application, service wiring, persistence,
  and Bubble Tea program creation.
- `cli.go`: CLI help and Bash, Zsh, and Fish completion generators.
- `config.go`: TOML schema, defaults, lookup paths, and validation.
- `keybindings.go`: configurable key groups, defaults, help labels, and
  contextual conflict validation.
- `github.go`: GitHub queries, pagination, mutations, capabilities, rate-limit
  reporting, and service interfaces.
- `cache.go`: immediate cached reads, offline fallback, content-aware writes,
  and bounded pruning.
- `tui.go`: main application state, updates, screens, rendering, refresh
  coordination, and contextual help.
- `pr_editor.go`, `text_editor.go`, `branch_completion.go`: PR metadata editor,
  reusable text editing, Vim-style motions/visual mode, and target-branch
  completion.
- `markdown.go`, `markdown_editor_highlight.go`: GitHub-flavored comment
  rendering and non-destructive editor highlighting.
- `highlight.go`, `suggestions.go`: syntax-highlighted diff hunks and GitHub
  suggestion previews.
- `theme.go`: built-in, custom, high-contrast, and no-color palettes.
- `health.go`: component health, stable status, rate limits, and session event
  history.
- `conflicts.go`: read-only conflicting-file discovery in a temporary bare Git
  repository; it must not depend on or modify the current Git/Jujutsu checkout.
- `drafts.go`, `persistence.go`: versioned, atomic local state.
- `ai.go`, `ai_diff.go`, `ai_codex.go`, `ai_store.go`, `ai_tui.go`:
  experimental local-only AI review, filtering, provider isolation, local
  storage, and UI.
- `types.go`: shared domain models and capability flags.
- `TODO.md`: future work; keep completed behavior out of open TODO sections.

Most source files have a corresponding `_test.go`. Add focused regression
tests beside the code being changed.

## Build and validation

Use the package, not an individual source file:

```sh
go run .
go test ./...
go test -race ./...
go vet ./...
go build ./...
```

Run `gofmt` on changed Go files. A normal implementation should at least pass
`go test ./...`; changes involving asynchronous refreshes, provider progress,
or shared persistence should also pass the race detector.

Do not use `go run main.go`: this repository relies on the other files in the
same package.

Do not run Git commands or alter repository history unless the user explicitly
asks. Preserve unrelated working-tree changes.

## Architecture and state flow

`App` is the Bubble Tea model. GitHub operations return typed messages to
`Update`; rendering belongs in `View` and feature-specific view helpers.
Network calls, subprocesses, and disk reads must not block the update loop.
Long operations should expose stable progress and support cancellation where
possible.

GitHub access is expressed through narrow service interfaces. Keep compile-time
interface assertions in `main.go` when implementations change. The cached
service must preserve the capability behavior of the live service rather than
silently bypassing write gates.

Refreshes are intentionally incremental:

- Render cached core data immediately when available.
- Replace it with live core data without blanking the current screen.
- Enrich checks, annotations, and conflict details independently.
- Retain the last complete subsection when one enrichment fails.
- Ignore results from superseded requests.

Do not turn partial failures into an all-or-nothing screen failure.

## GitHub correctness and write safety

- Paginate list-like GitHub data or make any remaining bound visible.
- Treat GraphQL partial data and errors deliberately.
- Use the authenticated endpoint consistently, including GitHub Enterprise
  Server URL derivation.
- Respect rate limits, retry windows, and adaptive polling.
- Check the exposed capability gate before showing or executing a mutation.
- Preserve drafts if a mutation or post-mutation refresh fails.
- Require confirmation for merge, auto-merge, and other consequential actions.
- Use expected head OIDs where GitHub supports them; reject stale prepared
  actions instead of applying them to a changed PR.
- Sanitize untrusted GitHub and subprocess text before terminal rendering.
- Never interpolate untrusted content into shell commands.

## Local persistence

Cache, state, drafts, and local-AI files are user data:

- Keep formats versioned.
- Write atomically.
- Use restrictive permissions for sensitive or user-authored content.
- Avoid rewriting unchanged files.
- Bound cache growth and preserve corrupt-file diagnostics in Health.
- Do not silently delete recoverable drafts or local review state.

## Text, Markdown, and terminal behavior

- Terminal width is a runtime constraint. Wrap help, errors, paths, Markdown,
  editor lines, and modal content without losing structural prefixes.
- Measure display cells, not bytes or rune counts.
- Editing and selections must operate on grapheme boundaries.
- Soft-wrapped editor rows are virtual display rows: navigation may traverse
  them, but saved GitHub Markdown must reconstruct the original logical lines.
- Syntax and Markdown highlighting must not insert, remove, or replace editable
  characters.
- Keep the active pane visually distinguishable.
- Compact footers show only the first configured key for each action; the help
  popup may show all configured alternatives.
- Add new actions to contextual help and keybinding validation.

## Themes

Do not hard-code feature colors outside the theme palette. New UI elements must
remain legible in built-in dark/light themes, custom themes, `high-contrast`,
and `no-color`. Syntax and Markdown highlighting should follow the selected
theme rather than an independent fixed palette.

## Experimental AI rules

The provider abstraction is intentionally broader than the current Codex CLI
implementation. Keep provider-specific parsing in its adapter.

- AI remains disabled by default.
- Every inference run requires an explicit user action and scope confirmation.
- The inference-free status check and quota-consuming provider test must remain
  visibly distinct.
- Filter excluded/sensitive files, redact secret-like values, and enforce byte,
  file, call, output, and result-count limits.
- Treat paths, code, PR text, and comments as untrusted prompt data.
- Validate findings against changed diff lines and the prepared head.
- Pin one exact model for a run; never silently fall back.
- Reject attempted tool, command, or file-change events.
- Only display provider-exposed reasoning summaries. Never request, infer, log,
  or display hidden chain-of-thought.
- Store findings locally with deterministic deduplication and mark them
  outdated when the PR head changes.

Any future provider that sends data to a direct API needs explicit privacy and
retention semantics documented before implementation.

## Change discipline

Prefer small, idiomatic changes that preserve current behavior. Correctness
comes before API consistency, and API consistency comes before refactoring.
Do not rewrite working subsystems merely for style.

When behavior changes:

1. Identify the active screen and input context.
2. Update state transitions and cancellation behavior.
3. Update rendering, contextual help, and capability explanations.
4. Add or update regression tests.
5. Update `README.md` for user-visible configuration or workflow changes.
6. Update `TODO.md` only when work is genuinely completed or newly deferred.

If a product decision would materially affect persistence compatibility,
GitHub writes, AI data exposure, destructive behavior, or default keybindings,
ask the repository owner rather than guessing.