diffowl 0.3.2 → 0.4.0

package/README.md

@@ -7,417 +7,240 @@
 " "
 ```
 
-> **The verification layer for agent-written code.**
->
-> An independent reviewer that runs locally on every commit — on the model you already use, no matter which agent (or human) wrote the code.
-
-Coding agents now write much of the code, but the agent that wrote a patch shouldn't be its only reviewer. DiffOwl is a separate, independent review pass: it builds bounded local context from your diff and asks a model for structured, durable findings. It works the same whether the change came from Claude Code, Cursor, OpenCode, or your own hands.
-
-Under the hood it drives a headless [OpenCode](https://opencode.ai/docs/server/) session for model execution, so you bring your own provider and pay no one but them — no DiffOwl account, no service in the loop.
-
----
-
-## Features
-
-- **Agent-Agnostic**: Reviews code from any source — Claude Code, Cursor, OpenCode, or a human. The reviewer stays independent from whoever wrote the patch.
-- **Provider-Neutral**: Runs on whatever model and provider you have configured in OpenCode (Copilot, OpenAI, local, and more). No separate keys, no DiffOwl account, no per-seat bill.
-- **First-Class TypeScript Support**: Automatically extracts modified TypeScript AST nodes (functions, classes, interfaces, types, enums, methods, properties, and top-level const declarations) to feed rich, structured context to the AI reviewer.
-- **Automatic Git Hooks**: Reviews run on every commit and stay out of your way — results land in `.diffowl/` when they are ready.
-- **Review Chat Handoff**: Reopen the OpenCode session behind the latest or any selected review with `diffowl chat`.
-- **Review Depth Profiles**: Choose `shallow` or `default` context strategies to match fast hooks or normal reviews.
-- **Intelligent File Filtering**: Supports `include` and `exclude` glob patterns to focus reviews on source directories while skipping build artifacts, lockfiles, and node modules.
-- **Project-Specific Rules**: Inject custom guidelines directly into the reviewer's system prompt (e.g., "Check for SQL injection", "Ensure TypeScript types are explicit").
-- **Interactive Model Selector**: Automatically queries OpenCode to present a clean, interactive list of your connected providers and models.
-- **Local Reports**: Generates markdown reviews under `.diffowl/reviews/`, including durable finding IDs and hidden session metadata that makes reports chat-capable.
-- **Durable Findings (0.3)**: Persists reviews and findings in `.diffowl/state.db` with stable `fnd_*` IDs, occurrence tracking, and lifecycle commands for fix, dismiss, defer, and reopen.
-- **Agent-Assisted Resolution**: Includes an optional portable skill that lets coding agents investigate findings, fix confirmed issues, record dismissals, and archive handled reports.
-- **Hook Log Retention**: Bounds accumulated hook logs without deleting review history.
-
----
-
-## Quick Start
-
-### 1. Prerequisites
-
-1. **Verify Node.js 22.14.0 or newer is installed**:
-   ```bash
-   node --version
-   ```
-2. **Install OpenCode CLI**:
-   ```bash
-   npm install --global opencode-ai
-   ```
-3. **Authenticate a provider and confirm a model is available**:
-   ```bash
-   opencode
-   ```
-   In OpenCode, connect or authenticate a provider such as GitHub Copilot, OpenAI, or Ollama. Confirm that at least one model is available before continuing.
-
-### 2. Install DiffOwl
+Review agent-written code with a second model before it ships.
 
-```bash
-npm install --global diffowl
-```
+DiffOwl is a local code review CLI. It builds focused context from a Git diff, sends that context to a model through [OpenCode](https://opencode.ai/docs/server/), and records actionable findings in your repository.
 
-### 3. Initialize DiffOwl in Your Repository
+It works with changes from any coding agent or human. You choose the model and provider through OpenCode. DiffOwl does not require an account, another API key, or a hosted DiffOwl service.
 
-To set up DiffOwl for your project, navigate to your target git repository and run:
-
-```bash
-diffowl init
-```
+## Why DiffOwl
 
-This will:
+The agent that wrote a change should not be its only reviewer. Asking it to review its own work can repeat the same assumptions that produced the bug.
 
-1. Start an OpenCode server if needed and `server.auto_start` is enabled.
-2. Fetch your connected providers and active models.
-3. Allow you to select a model interactively.
-4. Generate a `.diffowl.yml` configuration file in the current project.
+DiffOwl adds an independent pass between writing code and shipping it:
 
-> [!IMPORTANT]
-> DiffOwl uses OpenCode's existing provider credentials. It does not configure provider keys itself. If initialization reports no active models, run `opencode`, connect or re-authenticate a provider, confirm a model is available, and rerun `diffowl init`.
+- Review the last commit, staged changes, a specific commit, or a whole branch.
+- Use any model already connected to OpenCode, including local models.
+- Give the reviewer bounded local context instead of dumping the entire repository into a prompt.
+- Keep findings after the review ends, with stable IDs and lifecycle states.
+- Reopen the review session when a finding needs more investigation.
+- Run reviews automatically after commits without blocking them.
 
-### 4. Run Your First Review
+TypeScript reviews include changed AST symbols, related tests, file excerpts, and bounded call-flow context. Other languages still get diff-centered review with targeted repository exploration.
 
-```bash
-diffowl review
-```
+## How it works
 
-Read the latest report at `.diffowl/reviews/latest.md`, or install the optional resolution skill below to let a coding agent investigate and handle findings.
+1. DiffOwl reads the Git change you selected.
+2. It filters files and assembles relevant local context.
+3. A separate model reviews the change through a headless OpenCode session.
+4. DiffOwl writes a Markdown report and persists findings in SQLite.
+5. You inspect the findings, continue the review chat, or hand them to a coding agent for resolution.
 
-If a review reports an authentication or provider failure:
+The orchestration and state stay in your repository. Review context is sent to the provider you selected in OpenCode.
 
-1. Run `opencode`.
-2. Connect or re-authenticate the provider and confirm the configured model is available.
-3. Retry with `diffowl review`.
+## Quick start
 
-For a timeout, retry with less context:
+You need Node.js 22.14.0 or newer and an authenticated [OpenCode](https://opencode.ai/) provider.
 
 ```bash
-diffowl review --depth shallow
+npm install --global opencode-ai
+opencode
 ```
 
----
-
-## Resolve Findings With an Agent
-
-DiffOwl can use an inexpensive model for review generation while a stronger coding agent verifies and resolves the resulting findings. The optional `diffowl-resolve` skill works with agents that support the open [Agent Skills](https://skills.sh/) format.
-
-### Install the skill
-
-Install the `diffowl-resolve` skill:
+Connect a provider in OpenCode, then install and initialize DiffOwl:
 
 ```bash
-npx skills add gutierrezje/diffowl --skill diffowl-resolve
+npm install --global diffowl
+cd your-repository
+diffowl init
 ```
 
-The skills CLI installs into the current project by default. Restart or reload your agent if it does not immediately discover the new skill.
-
-### Use the skill
+`diffowl init` finds your available OpenCode models, lets you choose one, and writes `.diffowl.yml`.
 
-First generate a review:
+Review the last commit:
 
 ```bash
-diffowl review
-```
-
-Then ask your coding agent in plain language:
-
-```text
-Resolve the latest DiffOwl review.
-```
-
-Other useful prompts:
-
-```text
-Investigate finding 2 in the latest DiffOwl review.
-Resolve all open DiffOwl reviews.
-Resolve the latest 3 DiffOwl reviews.
-Check whether the older DiffOwl findings have already been fixed.
-Archive fully resolved DiffOwl reviews.
+diffowl
 ```
 
-The agent will:
-
-1. Treat findings as candidates and verify them against the current code.
-2. Fix confirmed issues using the repository's normal workflow.
-3. For durable findings (0.3+), record lifecycle status with `diffowl findings fix`, `dismiss`, or `defer`.
-4. For legacy reports, mark findings as fixed, already fixed, agent dismissed, user dismissed, deferred, or open in a `## Resolution` checklist.
-5. Append or merge resolution state without rewriting the generated review body.
-6. Move fully handled timestamped reports into `.diffowl/reviews/resolved/` when every finding is complete.
-
-`latest.md` is only a copy of the newest report and is overwritten by future reviews. Markdown reports from 0.3+ are immutable snapshots; SQLite is the authoritative backlog for durable findings.
-
-For legacy pre-0.3 reports, resolution state is appended under `## Resolution`. To reopen the OpenCode session for an archived report, pass its explicit path:
+Or review work before committing:
 
 ```bash
-diffowl chat .diffowl/reviews/resolved/review-<timestamp>.md
+git add -p
+diffowl review --staged
 ```
 
-### What the statuses mean
-
-| Status          | Meaning                                                       | Complete? |
-| --------------- | ------------------------------------------------------------- | --------- |
-| Fixed           | The agent changed code or configuration and verified the fix. | Yes       |
-| Already fixed   | Current code no longer exhibits the reported issue.           | Yes       |
-| Agent dismissed | Investigation showed the finding was noise or incorrect.      | Yes       |
-| User dismissed  | You explicitly chose not to address the finding.              | Yes       |
-| Deferred        | The issue is valid but intentionally left for later.          | No        |
-| Open            | The finding has not been fully investigated.                  | No        |
+The latest report is written to `.diffowl/reviews/latest.md`.
 
-Reports containing deferred or open findings remain in `.diffowl/reviews/`. DiffOwl never deletes review history automatically.
+## Choose what to review
 
-### Troubleshooting
+| Command                         | Reviews                                           |
+| ------------------------------- | ------------------------------------------------- |
+| `diffowl`                       | The last commit                                   |
+| `diffowl review --staged`       | Staged changes                                    |
+| `diffowl review --commit <ref>` | One commit                                        |
+| `diffowl review --base`         | Committed branch changes since the default branch |
+| `diffowl review --base <ref>`   | Committed branch changes since an explicit base   |
 
-- **No review exists:** Run `diffowl review` first, or install `diffowl hook install` and make a commit.
-- **The agent does not load the skill:** Verify project installation with `npx skills list` or global installation with `npx skills list --global`, then restart or reload the agent.
-- **The skill is installed for the wrong agent:** Reinstall with `--agent <agent-name>`, or use `--agent '*'` to install for every detected agent.
-- **A hook review timed out:** Run the retry command shown by the next foreground DiffOwl command, or retry manually with `diffowl review --commit <sha> --depth shallow`.
-- **You prefer manual resolution:** Edit code normally; the skill is optional and does not affect the DiffOwl CLI.
+Useful review options:
 
----
-
-## CLI Reference
-
-### `diffowl` (or `diffowl review`)
+```bash
+# Faster review with less context
+diffowl review --staged --depth shallow
 
-Runs a code review on your repository.
+# Use a different model once
+diffowl review --staged --model openai/gpt-5.6-luna
 
-- **Default**: Reviews the changes in the **last commit**.
-- `--staged`: Reviews currently **staged changes** instead of the last commit.
-- `--commit <ref>`: Reviews a specific commit ref instead of the last commit.
-- `--hook`: Runs in background, non-blocking mode (used by Git hook).
-- `--depth <depth>`: Overrides configured review depth. Valid values: `shallow`, `default`.
-- `--reasoning <effort>`: Overrides configured OpenCode reasoning variant. Valid values: `auto`, `none`, `minimal`, `low`, `medium`, `high`, `max`, `xhigh`.
-- `--verbose`: Includes suppressed findings and extra review details in the report.
-- `--format <format>`: Output format: `text` (default) or `json`. JSON writes a versioned document to stdout and persists SQLite state.
+# Emit a versioned JSON document for scripts
+diffowl review --base --format json
 
-Candidates below `min_confidence` or outside changed files are excluded from actionable finding counts and review status. When any are excluded, the report includes a short diagnostic summary and points to `diffowl chat` for investigation. Outside-file candidates are shown in full with `--verbose`; below-threshold candidates remain available in the OpenCode session.
+# Exit 1 when actionable findings remain
+diffowl review --base --fail-on-findings
+```
 
-Rendered findings use stable `Finding N` headings. Reports from DiffOwl 0.3+ also include durable `fnd_*` IDs and observation classification (`new`, `existing`, `regressed`), making prompts such as “investigate finding 2” or `diffowl findings show fnd_abc` map directly to the backlog.
+Branch review uses the merge base through `HEAD`, matching the committed diff in a pull request. It does not include staged or unstaged changes.
 
-Review depth controls both how much local context DiffOwl preloads and how much exploration the reviewer is expected to do:
+## Work with findings
 
-- `shallow`: Cheap, surface-level review. Uses a smaller diff-centered prompt with no AI tools enabled. It is expected to miss deeper issues, but can catch obvious local bugs such as off-by-one errors, inverted conditions, unsafe null handling, missing awaits, and implementation anti-patterns visible in the diff.
-- `default`: Normal review. Includes changed TypeScript AST symbols, small file excerpts, related tests, and bounded Potential Call Flow snippets from `git grep`. Permissionless read/search tools are enabled for targeted exploration when context is incomplete; permission prompts are rejected.
+DiffOwl stores durable findings in `.diffowl/state.db`. A finding stays open until someone records what happened to it. A later model review that fails to mention it does not silently mark it fixed.
 
 ```bash
-# Review last commit
-diffowl
-
-# Review staged files
-diffowl review --staged
-
-# Review a specific commit
-diffowl review --commit abc1234
+# List unresolved findings
+diffowl findings
 
-# Include suppressed outside-file findings in the report
-diffowl review --staged --verbose
+# Inspect a finding by ID, ID prefix, or latest:N
+diffowl findings show fnd_abc
 
-# Request a high reasoning variant for models that support it
-diffowl review --staged --reasoning high
+# Record the outcome
+diffowl findings fix fnd_abc --note "Added a null guard." --verified-by "pnpm run test"
+diffowl findings dismiss fnd_abc --reason "The caller already validates this value."
+diffowl findings defer fnd_abc --reason "Blocked by an upstream change."
+diffowl findings reopen fnd_abc --reason "The bug returned in a new path."
 ```
 
-### `diffowl model`
+Use `--format json` with `findings list`, `show`, or `summary` when another tool needs the backlog.
 
-View or interactively change the active AI model.
+To continue the conversation behind a review:
 
 ```bash
-# Interactively pick a model
-diffowl model
-
-# Manually set a model
-diffowl model opencode/big-pickle
+diffowl chat
+diffowl chat .diffowl/reviews/review-<timestamp>.md
 ```
 
-### `diffowl chat [report]`
+## Resolve findings with a coding agent
 
-Opens the OpenCode session associated with a review report. DiffOwl hands control to the OpenCode TUI rather than implementing a separate chat interface.
+The optional `diffowl-resolve` skill lets a coding agent investigate findings instead of accepting the review at face value. It verifies each candidate against the current code, fixes confirmed problems, records dismissals or deferrals, and preserves the report history.
 
 ```bash
-# Interactively select a review
-diffowl chat
+npx skills add gutierrezje/diffowl --skill diffowl-resolve
+```
 
-# Open a specific timestamped report directly
-diffowl chat review-2026-06-07T07-30-42-762Z.md
+Restart or reload the agent, then ask:
 
-# Use an explicit relative or absolute report path
-diffowl chat ./.diffowl/reviews/latest.md
+```text
+Resolve the latest DiffOwl review.
 ```
 
-Without an argument, DiffOwl displays active and resolved timestamped reports newest first. Bare filenames are resolved under `.diffowl/reviews/`, so agents and scripts can open a report deterministically without using the picker. Each chat-capable report stores its OpenCode session ID and project root in YAML frontmatter. Reports created before this feature and documentation-only skip reports do not have an OpenCode session to reopen.
+You can also ask it to investigate one finding, resolve every open review, or archive reports whose findings are fully handled.
 
-### `diffowl hook install | status | uninstall`
+## Run reviews automatically
 
-Installs or removes a managed post-commit Git hook that runs reviews automatically and asynchronously in the background.
+Install the non-blocking post-commit hook:
 
 ```bash
-# Install non-blocking post-commit review hook
 diffowl hook install
-
-# Check whether the hook is installed and up to date
-diffowl hook status
-
-# Uninstall the hook
-diffowl hook uninstall
 ```
 
-_Runs reviews asynchronously in the background, saving execution output to `.diffowl/hook.log` and the latest report to `.diffowl/reviews/latest.md`. Hook reviews use the configured `context.depth`, return control to your terminal instantly, and avoid clobbering any existing post-commit hook scripts._
-
-Only one hook review runs per project at a time. Each commit is recorded under `.diffowl/pending-reviews/`, and a background worker processes pending commits in order. Successful reviews remove their marker; failed reviews remain pending and are retried when a later commit triggers the hook. Review failures are recorded with their commit SHA in `.diffowl/last-hook-status.json` and reported on the next foreground review with commands to retry at default or shallow depth. Result files without a matching pending marker are removed automatically.
-
-### `diffowl server start | stop | status`
-
-Manually manage the OpenCode server lifecycle.
+The hook queues each commit, returns control to the terminal, and writes output to `.diffowl/hook.log`. Failed reviews remain pending and retry after a later commit.
 
 ```bash
-# Check if OpenCode serve is running
-diffowl server status
-
-# Start it manually
-diffowl server start
-
-# Stop the server
-diffowl server stop
+diffowl hook status
+diffowl hook uninstall
 ```
 
-### `diffowl findings [list] | show | dismiss | defer | fix | reopen`
-
-Inspect and manage the durable findings backlog stored in the repo's shared `.diffowl/state.db`.
+Claude Code users can also show the current finding summary when a session starts:
 
 ```bash
-# List unresolved findings (open and regressed)
-diffowl findings
-
-# Inspect one finding by full id, id prefix, or latest:N
-diffowl findings show fnd_abc --format json
-
-# Mark fixed after verification
-diffowl findings fix fnd_abc --note "Added null guard." --verified-by "pnpm run test"
-
-# Dismiss a false positive
-diffowl findings dismiss fnd_abc --reason "Guarded by caller."
-
-# Defer intentionally
-diffowl findings defer fnd_abc --reason "Needs upstream change."
-
-# Reopen a previously fixed or dismissed finding
-diffowl findings reopen fnd_abc --reason "Regression in new path."
+diffowl agent-hook install --client claude
 ```
 
-The unresolved backlog is durable: a finding does not auto-resolve just because a later review fails to mention it. Absence from a later model review never marks a finding fixed.
+## Configuration
 
----
-
-## Configuration (`.diffowl.yml`)
-
-Your `.diffowl.yml` configures everything for DiffOwl in your project:
+Project review policy lives in `.diffowl.yml`. Model selection is personal and stays in the shared, gitignored `.diffowl/preferences.yml`.
 
 ```yaml
-# Model to use for reviews (provider/model)
-model: opencode/big-pickle
-
-# OpenCode server settings
-server:
-  port: 4096
-  auto_start: true
-
-# Local review context strategy: shallow or default
 context:
   depth: default
 
-# OpenCode model variant for reasoning/thinking effort.
-# auto leaves the selected model/provider default alone.
 reasoning:
   effort: auto
 
-# Hook log retention. Set to 0 for unlimited retention.
-retention:
-  # Before each hook review, retain approximately this many KiB
-  # of previous hook.log output. The new run may exceed this target.
-  hook_log_kb: 1024
+gate:
+  fail_on_findings: false
 
-# Review timeout in seconds
 timeout: 300
-
-# Minimum confidence level of findings to report: low, medium, or high
 min_confidence: medium
-
-# Skip reviews when every changed file is documentation-like
 skip_doc_only: false
 
-# Include suppressed outside-file findings and extra details in reports
-verbose: false
-
-# Review scope
 include:
   - "src/**/*"
-  - "lib/**/*"
 
 exclude:
   - "**/*.test.*"
-  - "**/*.spec.*"
   - "**/*.lock"
-  - "**/node_modules/**"
   - "**/dist/**"
-  - "**/build/**"
 
-# Custom project-specific review rules
 rules:
-  - "Check for potential security vulnerabilities like SQL injection or SSRF"
-  - "Flag any hardcoded secrets, tokens, or private keys"
-  - "Suggest readability and architectural improvements where relevant"
-```
-
----
-
-## Review Files
-
-Each completed review starts with a timestamped report and an ephemeral `latest.md` copy. Durable state and reports are anchored to the repository's primary checkout, so linked Git worktrees share one backlog. Checkout-scoped runtime files such as hook status, hook logs, and `server.pid` stay in that checkout's local `.diffowl/`. The optional resolution skill moves fully handled timestamped reports into the resolved archive:
-
-```text
-.diffowl/state.db                                 # Authoritative review and finding state (0.3+)
-.diffowl/reviews/review-<timestamp>.md           # Immutable markdown export snapshot
-.diffowl/reviews/latest.md                       # Ephemeral copy of the newest report
-.diffowl/reviews/resolved/review-<timestamp>.md  # Fully handled report archived by the skill
+  - "Flag hardcoded secrets."
+  - "Check authorization at every write boundary."
 ```
 
-Review reports include YAML frontmatter similar to:
+Choose or change your model without editing project policy:
 
-```yaml
----
-diffowl:
-  schema_version: 1
-  review_id: rev_...
-  session_id: ses_...
-  project_root: /path/to/project
----
+```bash
+diffowl model
+diffowl model provider/model
+diffowl model --reset
 ```
 
-Finding headings in 0.3+ reports look like:
+Configuration is deep-merged with defaults, so the file only needs the settings your repository changes.
 
-```md
-#### Finding 1 (`fnd_...`) — **new**
+## Files DiffOwl creates
 
-**[WARNING] src/auth.ts:12**
-Missing null check
+```text
+.diffowl.yml                                  # Committed project policy
+.diffowl/preferences.yml                      # Gitignored personal model choice
+.diffowl/state.db                             # Authoritative findings backlog
+.diffowl/reviews/review-<timestamp>.md        # Immutable review snapshot
+.diffowl/reviews/latest.md                    # Copy of the newest report
+.diffowl/reviews/resolved/                    # Reports archived by the resolution skill
 ```
 
-This metadata is used by `diffowl chat`. For legacy pre-0.3 reports, agents may append a `## Resolution` section. For 0.3+ reports, use `diffowl findings *` only—do not edit markdown. DiffOwl does not delete review history automatically.
+Linked Git worktrees share the durable backlog and review reports from the primary checkout. Runtime files such as hook logs and server state remain checkout-specific.
+
+## Command reference
 
-### Upgrading to 0.3
+| Command              | Purpose                                     |
+| -------------------- | ------------------------------------------- |
+| `diffowl init`       | Configure DiffOwl in the current repository |
+| `diffowl review`     | Run a review                                |
+| `diffowl model`      | View or change the selected model           |
+| `diffowl findings`   | Inspect and update durable findings         |
+| `diffowl chat`       | Reopen an OpenCode review session           |
+| `diffowl hook`       | Manage the post-commit hook                 |
+| `diffowl agent-hook` | Manage supported agent client hooks         |
+| `diffowl server`     | Manage the local OpenCode server            |
 
-- **No import step**: Existing markdown reports remain unchanged and chat-capable. They are not imported into SQLite.
-- **New reviews persist state**: After upgrading, each `diffowl review` writes both SQLite state and a markdown snapshot.
-- **Backlog semantics change**: Use `diffowl findings` for the unresolved backlog. Markdown `### Status` reflects the review snapshot only.
-- **Resolution workflow**: Prefer `diffowl findings fix|dismiss|defer` over editing report checklists when durable findings exist. Never mark fixed without recorded verification (`--verified-by`).
-- **Not in 0.3**: Semantic deduplication beyond fingerprint matching, automatic resolution when findings disappear, legacy report migration, retention cleanup, and SARIF export.
+Run `diffowl <command> --help` for every option.
 
----
+## Troubleshooting
 
-## Developing
+- No models found: run `opencode`, connect or re-authenticate a provider, then rerun `diffowl init`.
+- Review timed out: retry with `diffowl review --depth shallow`.
+- Hook review failed: run the retry command shown by the next foreground DiffOwl command, or inspect `.diffowl/hook.log`.
+- Agent did not load `diffowl-resolve`: verify it with `npx skills list`, then restart or reload the agent.
 
-Clone the repository and link the CLI globally:
+## Develop locally
 
 ```bash
 git clone https://github.com/gutierrezje/diffowl.git
@@ -427,23 +250,14 @@ pnpm run build
 pnpm link --global
 ```
 
-When making edits to `src/**`, rebuild to update the linked CLI and git hooks:
+Run the checks:
 
 ```bash
-pnpm run build
-git add -p
-diffowl review --staged
+pnpm run lint
+pnpm run test
 ```
 
-To verify model discovery against an authenticated OpenCode server already running on port 4096:
-
-```bash
-DIFFOWL_INTEGRATION=1 pnpm exec vitest run src/opencode/models.integration.test.ts
-```
-
-Set `DIFFOWL_OPENCODE_PORT` when the server uses a different port. This live test is skipped during the normal test suite.
-
----
+After changing `src/**`, rebuild before testing the globally linked `diffowl` command.
 
 ## License