diffowl 0.3.1 → 0.3.3

package/README.md

@@ -186,11 +186,13 @@ Runs a code review on your repository.
 - **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.
+- `--base [ref]`: Reviews all committed branch changes since the merge base with `ref`. With no
+  ref, DiffOwl detects `origin/HEAD`, then local `main` or `master`.
 - `--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.
+- `--format <format>`: Output format: `text` (default) or `json`. JSON writes a versioned document to stdout and persists SQLite state. Review `status` is `open` when unsuppressed `error`/`warning` findings remain, `advisory` when only `info` findings remain, `resolved` when none remain, or `skipped`.
 
 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.
 
@@ -211,6 +213,15 @@ diffowl review --staged
 # Review a specific commit
 diffowl review --commit abc1234
 
+# Review this branch against the default branch
+diffowl review --base
+
+# Review this branch against an explicit base
+diffowl review --base main
+
+# Review a stacked branch against its parent branch
+diffowl review --base feature/parent-branch
+
 # Include suppressed outside-file findings in the report
 diffowl review --staged --verbose
 
@@ -218,18 +229,33 @@ diffowl review --staged --verbose
 diffowl review --staged --reasoning high
 ```
 
+Branch review uses merge-base-to-`HEAD` semantics, matching the committed diff shown by a pull
+request. It never includes staged or unstaged changes. `--base` cannot be combined with `--staged`
+or `--commit`; use those as separate review surfaces.
+
 ### `diffowl model`
 
-View or interactively change the active AI model.
+View or change the active AI model. This stores a personal preference in the repository's shared,
+gitignored `.diffowl/preferences.yml`, so every linked worktree uses the same model without changing
+the committed `.diffowl.yml`.
 
 ```bash
 # Interactively pick a model
 diffowl model
 
 # Manually set a model
-diffowl model opencode-go/big-pickle
+diffowl model opencode/big-pickle
+
+# Remove the personal selection
+diffowl model --reset
+
+# Override the model for one review only
+diffowl review --model openai/gpt-5.6-luna
 ```
 
+Model precedence is `--model`, then `DIFFOWL_MODEL`, then the shared local preference. Without one,
+review commands ask you to configure a model rather than assuming provider access.
+
 ### `diffowl chat [report]`
 
 Opens the OpenCode session associated with a review report. DiffOwl hands control to the OpenCode TUI rather than implementing a separate chat interface.
@@ -283,12 +309,15 @@ diffowl server stop
 
 ### `diffowl findings [list] | show | dismiss | defer | fix | reopen`
 
-Inspect and manage the durable findings backlog stored in `.diffowl/state.db`.
+Inspect and manage the durable findings backlog stored in the repo's shared `.diffowl/state.db`.
 
 ```bash
 # List unresolved findings (open and regressed)
 diffowl findings
 
+# Machine-readable backlog for agents and scripts
+diffowl findings --format json
+
 # Inspect one finding by full id, id prefix, or latest:N
 diffowl findings show fnd_abc --format json
 
@@ -305,18 +334,19 @@ diffowl findings defer fnd_abc --reason "Needs upstream change."
 diffowl findings reopen fnd_abc --reason "Regression in new path."
 ```
 
+`list` and `show` default to text; the mutation commands (`fix`, `dismiss`, `defer`, `reopen`) default to JSON because they are primarily agent-invoked — pass `--format text` for human-readable output.
+
 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 (`.diffowl.yml`)
 
-Your `.diffowl.yml` configures everything for DiffOwl in your project:
+Your committed `.diffowl.yml` configures repository review policy. Model selection is deliberately
+absent because provider access belongs to each developer. Legacy `model` keys remain readable for
+compatibility but are ignored and removed the next time DiffOwl saves project config.
 
 ```yaml
-# Model to use for reviews (provider/model)
-model: opencode-go/big-pickle
-
 # OpenCode server settings
 server:
   port: 4096
@@ -373,7 +403,7 @@ rules:
 
 ## Review Files
 
-Each completed review starts with a timestamped report and an ephemeral `latest.md` copy. The optional resolution skill moves fully handled timestamped reports into the resolved archive:
+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+)
@@ -409,7 +439,7 @@ This metadata is used by `diffowl chat`. For legacy pre-0.3 reports, agents may
 
 - **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.
+- **Backlog semantics change**: Use `diffowl findings` for the unresolved backlog. Markdown `### Status` is `Open` (error/warning findings), `Advisory` (info-only), or `Resolved` (none); it 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.