feat(diff): remove arb diff command

The command does not provide enough value over `arb exec git diff` to
justify its maintenance cost and CLI surface area. Its only meaningful
coordination value is merge-base resolution, which is a single
well-known git command. See DR-0096.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: henrikje

GUIDELINES.md

@@ -24,7 +24,7 @@ Beyond showing honest state, Arborist actively watches for conditions that signa
 
 ### Coordination and overview, not authoring
 
-Arborist coordinates multi-repo operations (push, rebase, merge) and provides workspace-level overview (status, log, diff). It does not replace Git for authoring operations. Committing, staging, interactive rebase, and PR creation belong to direct interaction with each repository. `arb exec` bridges the gap for anything Arborist doesn't cover.
+Arborist coordinates multi-repo operations (push, rebase, merge) and provides workspace-level overview (status, log). It does not replace Git for authoring operations. Committing, staging, interactive rebase, and PR creation belong to direct interaction with each repository. `arb exec` bridges the gap for anything Arborist doesn't cover.
 
 ### Do one thing and do it well
 
@@ -95,7 +95,7 @@ Tell the user *what happened*, not just *that it happened*. Use descriptive per-
 
 **State-changing commands** (`push`, `pull`, `rebase`, `merge`, `reset`, `retarget`): accept optional `[repos...]` to narrow scope; default to all repos. Follow the five-phase workflow: assess → plan → confirm → execute → summarize. Each defines a typed assessment interface classifying repos into will-operate / up-to-date / skip-with-reason.
 
-**Overview commands** (`status`, `log`, `diff`) are read-only. They scope to the feature branch via base branch resolution, skip detached/drifted repos with explanation, and support `[repos...]` filtering, `--json`, and `--verbose`.
+**Overview commands** (`status`, `log`) are read-only. They scope to the feature branch via base branch resolution, skip detached/drifted repos with explanation, and support `[repos...]` filtering, `--json`, and `--verbose`.
 
 ### Expected flags per command category
 
@@ -122,7 +122,7 @@ Individual sync commands add domain-specific flags (`--force`, `--autostash`, `-
 | `--all-repos` (`-a`) | Select all repos (scripting) |
 | Interactive picker | When no args and TTY |
 
-**Overview commands** (`status`, `log`, `diff`):
+**Overview commands** (`status`, `log`):
 
 | Flag | Purpose |
 |------|---------|
@@ -142,7 +142,7 @@ When multiple operations manage the same `.arb/` subsystem (repos, templates), g
 
 **`pull`** always fetches — it inherently needs fresh remote state to assess what to pull. It does not offer `--no-fetch`.
 
-**Content commands** (`log`, `diff`) do not fetch by default — stale content is less confusing. `--fetch` opts in.
+**`log`** does not fetch by default — stale content is less confusing. `--fetch` opts in.
 
 The `ARB_NO_FETCH` environment variable globally suppresses automatic fetching — equivalent to passing `-N` to every command. Explicit `--fetch` overrides it. `pull` is unaffected (it always fetches). See `decisions/0045-universal-fetch-flags.md` and `decisions/0087-arb-no-fetch-env-var.md`.
 
@@ -174,9 +174,9 @@ When repos are the command's primary target, they are positional arguments (`arb
 
 ### Status-based filtering: `--where` and `--dirty`
 
-`--where` (`-w`) filters repos by `RepoFlags`. Supported on every command that gathers workspace status: `status`, `diff`, `log`, `exec`, `open`, `list`, `delete`, `push`, `pull`, `rebase`, `merge`, `reset`. Commands that don't gather status (e.g. `attach`, `create`, `branch rename`) do not get `--where`.
+`--where` (`-w`) filters repos by `RepoFlags`. Supported on every command that gathers workspace status: `status`, `log`, `exec`, `open`, `list`, `delete`, `push`, `pull`, `rebase`, `merge`, `reset`. Commands that don't gather status (e.g. `attach`, `create`, `branch rename`) do not get `--where`.
 
-`--dirty` (`-d`) is a shorthand for `--where dirty`, mutually exclusive with `--where`. Only offered where "dirty" is a natural filter: `status`, `diff`, `log`, `exec`, `open`, `list`. Omitted from sync commands and `delete`.
+`--dirty` (`-d`) is a shorthand for `--where dirty`, mutually exclusive with `--where`. Only offered where "dirty" is a natural filter: `status`, `log`, `exec`, `open`, `list`. Omitted from sync commands and `delete`.
 
 Filter terms are organized by orthogonal dimension (see ARCHITECTURE.md). Positional terms use the `<position>-<axis>` pattern (`ahead-share`, `behind-base`) so axis relationships are obvious. Filter names describe state, not suggested action — whether a repo "needs rebase" depends on the user's intent; the filter just says `behind-base`. Named positive terms exist only where they provide non-trivial composition (`pushed` = `^ahead-share+^no-share`) or are natural vocabulary (`clean`, `safe`); trivially-derivable positives use `^` negation instead (`^behind-base` rather than a named `synced-base`).
 

QA.md

@@ -58,7 +58,7 @@ Check that similar commands follow the same patterns as defined in GUIDELINES.md
 
 - State-changing commands (`push`, `pull`, `rebase`, `merge`, `reset`, `retarget`) all follow the five-phase mutation flow.
 - Membership-changing commands (`attach`, `detach`, `create`) handle `[repos...]`, interactive picker, `--all-repos`, and non-TTY errors consistently.
-- Overview commands (`status`, `log`, `diff`) handle `--fetch`/`--no-fetch`, `--json`, `[repos...]` consistently. They must not fetch by default.
+- Overview commands (`status`, `log`) handle `--fetch`/`--no-fetch`, `--json`, `[repos...]` consistently. They must not fetch by default.
 - Mutation commands (`push`, `rebase`, `merge`) must fetch by default. `exec` and `open` must not have fetch flags.
 - `--where` filtering works the same everywhere it appears. Filter terms must be anchored to `FILTER_TERMS` in `status.ts` — no ad-hoc string comparisons.
 - `--force` has per-command semantics (plan modifier in `push`, safety bypass in `delete`). Verify that help text and behavior match each command's specific contract.

README.md

@@ -352,7 +352,7 @@ arb exec npm install          # run a command in every repo
 arb status -w dirty,unpushed  # filter repos by status flags
 ```
 
-All state-changing commands support `--dry-run` to preview the plan and `--yes` to skip confirmation prompts. `status`, `branch`, `list`, `log`, `diff`, and `repo list` support `--json` for structured output and `--quiet` for one name per line — useful for feeding into other commands. `arb exec` runs any command in each repo; `--where` (`-w`) filters repos by status flags like `dirty`, `behind-base`, or `ahead-share` and works across most commands. Exit codes are meaningful: 0 for success, 1 for issues, 130 for user abort. Human-facing output goes to stderr, machine-parsable data to stdout — so piping works naturally.
+All state-changing commands support `--dry-run` to preview the plan and `--yes` to skip confirmation prompts. `status`, `branch`, `list`, `log`, and `repo list` support `--json` for structured output and `--quiet` for one name per line — useful for feeding into other commands. `arb exec` runs any command in each repo; `--where` (`-w`) filters repos by status flags like `dirty`, `behind-base`, or `ahead-share` and works across most commands. Exit codes are meaningful: 0 for success, 1 for issues, 130 for user abort. Human-facing output goes to stderr, machine-parsable data to stdout — so piping works naturally.
 
 ## Alternatives
 

decisions/0096-remove-diff-command.md

@@ -0,0 +1,49 @@
+# Remove the diff command
+
+Date: 2026-03-26
+
+## Context
+
+DR-0023 introduced `arb diff` as the third overview command alongside `status` and `log`, forming a coherent triad. The command shows the cumulative diff of the feature branch since diverging from the base branch across all repos, with TTY, pipe, and JSON output modes.
+
+After using the command in practice, the value proposition turned out to be thin. In a workspace with multiple repos, the full diff across all repos is overwhelming and rarely useful — developers diff interactively in their editor or one repo at a time. The `--stat` summary mode was the most useful output, but it remains a thin wrapper around `git diff --stat` with merge-base resolution.
+
+## Options
+
+### A: Remove `arb diff` entirely
+
+Users who need the diff use `arb exec -- git diff --stat $(git merge-base origin/main HEAD)` or work in individual repos.
+
+- **Pros:** Maximum surface area reduction (~500 lines of command code, ~587 lines of integration tests). Simplifies the overview layer. One fewer command to learn, document, test, and maintain.
+- **Cons:** Breaks the "overview triad" from DR-0023. Loses cross-repo summary stats and JSON output.
+
+### B: Fold diff into `arb log --diff`
+
+Add a `--diff` flag to `arb log` that shows per-commit patches or cumulative diffstat.
+
+- **Pros:** Retains some diff capability.
+- **Cons:** Cumulative changeset and per-commit patches are fundamentally different operations. Expands log's scope beyond its core question, violating "do one thing well." `--verbose` already shows per-commit changed files.
+
+### C: Keep `arb diff` (status quo)
+
+No changes.
+
+- **Pros:** The triad remains complete.
+- **Cons:** Maintaining a command with thin value.
+
+## Decision
+
+Option A: remove `arb diff` entirely.
+
+## Reasoning
+
+The "Evaluating new operations" framework in GUIDELINES.md asks: "Would `arb exec` leave users meaningfully worse off?" For diff, the answer is no. The command does not involve conflict prediction, divergence analysis, plan/confirm flows, or state machines — the hallmarks of commands that earn their place per the "Minimal, semantic CLI" principle. Its only meaningful coordination value is merge-base resolution, which is a single well-known git command.
+
+Option B was rejected because grafting cumulative-diff semantics onto `arb log` creates conceptual confusion. If the command does not earn its place as a standalone, attaching it to another command does not change that.
+
+## Consequences
+
+- The overview command layer is now `status` and `log`. GUIDELINES.md references are updated accordingly.
+- DR-0023 remains unchanged as a historical record. Its reasoning about the authoring boundary (`arb commit`, `arb pr`) still holds; only the diff inclusion is reversed.
+- DR-0031 (diff merge-base against working tree) is now historical context with no active code.
+- Users who relied on `arb diff --json` for scripting need to adapt. This is acceptable during pre-release per "Prefer correctness over backwards compatibility."

docs/scripting-automation.md

@@ -46,7 +46,7 @@ arb delete --all-safe --where gone          # batch-remove workspaces whose bran
 
 For workspace-level commands (`list`, `delete`), AND applies per-repo: a workspace matches `dirty+ahead-share` only if a _single_ repo is both dirty and ahead-share, not if one repo is dirty and a different repo is ahead-share.
 
-`--where` is supported on `status`, `exec`, `open`, `diff`, `log`, `list`, `delete`, `push`, `pull`, `rebase`, `merge`, and `reset`. On `status`, `exec`, `open`, `diff`, `log`, and `list`, the shorthand `--dirty` (`-d`) is equivalent to `--where dirty`.
+`--where` is supported on `status`, `exec`, `open`, `log`, `list`, `delete`, `push`, `pull`, `rebase`, `merge`, and `reset`. On `status`, `exec`, `open`, `log`, and `list`, the shorthand `--dirty` (`-d`) is equivalent to `--where dirty`.
 
 The full list of filter terms:
 
@@ -120,7 +120,7 @@ Commands that accept `[repos...]` or `[names...]` also read names from stdin whe
 
 ```bash
 arb status -q --where dirty | arb exec git stash  # stash only dirty repos (exec doesn't read stdin)
-arb status -q --where ahead-share | arb diff         # diff only ahead-share repos
+arb status -q --where ahead-share | arb log          # log only ahead-share repos
 arb list -q --where gone | arb delete -y          # delete gone workspaces
 arb status -q | grep -v legacy | arb rebase -y    # rebase all except "legacy"
 ```
@@ -132,7 +132,7 @@ arb push --where ^behind-base -y      # only push repos that are already rebased
 arb rebase --where ^diverged -y       # skip diverged repos, rebase the easy ones
 ```
 
-Stdin-accepting commands: `create`, `attach`, `detach`, `status`, `diff`, `log`, `push`, `pull`, `rebase`, `merge`, `reset`, `delete`.
+Stdin-accepting commands: `create`, `attach`, `detach`, `status`, `log`, `push`, `pull`, `rebase`, `merge`, `reset`, `delete`.
 
 `exec` and `open` are excluded because they inherit stdin for child processes. Use xargs instead:
 
@@ -142,14 +142,13 @@ arb status -q --where dirty | xargs -I{} arb exec --repo {} make test
 
 ## Machine-readable output
 
-Six commands support `--json` for structured output to stdout:
+Five commands support `--json` for structured output to stdout:
 
 | Command | Output shape |
 |---------|-------------|
 | `arb status --json` | Object with `workspace`, `branch`, `base`, `repos[]`, aggregates |
 | `arb list --json` | Array of workspace objects with status counts and labels |
 | `arb log --json` | Object with `workspace`, `branch`, `base`, `repos[]`, `totalCommits` |
-| `arb diff --json` | Object with `workspace`, `branch`, `base`, `repos[]`, file/line totals |
 | `arb branch --json` | Object with `branch`, `base`, per-repo branches |
 | `arb repo list --json` | Array of repo entries with remote role detail |
 

docs/sync.md

@@ -113,6 +113,6 @@ All commands show a plan before proceeding. Add `--verbose` (`-v`) to see the ac
 | Sync commands (`push`, `rebase`, `merge`) | Yes | `--no-fetch` (`-N`) |
 | `pull` | Always | (no opt-out) |
 | Dashboard commands (`status`, `list`) | Yes | `--no-fetch` (`-N`) |
-| Content commands (`log`, `diff`) | No | `--fetch` |
+| `log` | No | `--fetch` |
 
 Set `ARB_NO_FETCH` to disable automatic fetching globally — equivalent to passing `-N` to every command. Explicit `--fetch` overrides the env var. `pull` always fetches regardless, since it inherently needs fresh remote state.

shell/arb.bash

@@ -469,20 +469,6 @@ __arb_complete_log() {
     COMPREPLY=($(compgen -W "$(__arb_workspace_repo_names "$base_dir")" -- "$cur"))
 }
 
-__arb_complete_diff() {
-    local base_dir="$1" cur="$2"
-    local prev="${COMP_WORDS[COMP_CWORD-1]}"
-    if [[ "$prev" == "-w" || "$prev" == "--where" ]]; then
-        __arb_complete_where_value "$cur"
-        return
-    fi
-    if [[ "$cur" == -* ]]; then
-        COMPREPLY=($(compgen -W "--fetch -N --no-fetch --stat --json --schema -d --dirty -w --where" -- "$cur"))
-        return
-    fi
-    COMPREPLY=($(compgen -W "$(__arb_workspace_repo_names "$base_dir")" -- "$cur"))
-}
-
 __arb_complete_pull() {
     local base_dir="$1" cur="$2"
     local prev="${COMP_WORDS[COMP_CWORD-1]}"
@@ -657,7 +643,7 @@ __arb_complete_template() {
 __arb_complete_help() {
     local base_dir="$1" cur="$2"
     local topics="filtering remotes stacked templates scripting"
-    local commands="init repo create delete rename list path cd attach detach status watch branch pull push rebase retarget merge reset undo log diff exec open template"
+    local commands="init repo create delete rename list path cd attach detach status watch branch pull push rebase retarget merge reset undo log exec open template"
     COMPREPLY=($(compgen -W "$topics $commands" -- "$cur"))
 }
 
@@ -683,7 +669,7 @@ _arb() {
 
     # Completing the subcommand itself
     if ((COMP_CWORD <= cmd_pos)); then
-        local commands="init repo create delete rename list path cd attach detach status watch branch pull push rebase retarget merge reset log diff exec open template help"
+        local commands="init repo create delete rename list path cd attach detach status watch branch pull push rebase retarget merge reset log exec open template help"
         # Also complete global flags
         if [[ "$cur" == -* ]]; then
             COMPREPLY=($(compgen -W "-C -h --help --version --debug" -- "$cur"))
@@ -717,7 +703,6 @@ _arb() {
         reset)    __arb_complete_reset "$base_dir" "$cur" ;;
         undo)     COMPREPLY=($(compgen -W "-y --yes -n --dry-run -f --force" -- "$cur")) ;;
         log)      __arb_complete_log "$base_dir" "$cur" ;;
-        diff)     __arb_complete_diff "$base_dir" "$cur" ;;
         exec)     __arb_complete_exec "$base_dir" "$cur" ;;
         open)     __arb_complete_open "$base_dir" "$cur" ;;
         template) __arb_complete_template "$base_dir" "$cur" ;;

shell/arb.zsh

@@ -200,7 +200,6 @@ _arb() {
                 'reset:Reset all repos to the share branch (or base if not pushed)'
                 'undo:Undo the last workspace operation'
                 'log:Show feature branch commits across repos'
-                'diff:Show feature branch diff across repos'
                 'exec:Run a command in each repo'
                 'open:Open repos in an application'
                 'template:Manage workspace templates'
@@ -561,17 +560,6 @@ _arb() {
                         '(-d --dirty -w --where)'{-w,--where}'[Filter repos by status flags]:filter:_arb_where_filter' \
                         '*:repo:($ws_repo_names)'
                     ;;
-                diff)
-                    _arguments \
-                        '(-N --fetch --no-fetch)--fetch[Fetch before showing diff]' \
-                        '(-N --fetch --no-fetch)'{-N,--no-fetch}'[Skip fetching (default)]' \
-                        '--stat[Show diffstat summary instead of full diff]' \
-                        '(--json --schema)--json[Output structured JSON]' \
-                        '(--schema --json)--schema[Print JSON Schema for --json output]' \
-                        '(-d --dirty -w --where)'{-d,--dirty}'[Only diff dirty repos]' \
-                        '(-d --dirty -w --where)'{-w,--where}'[Filter repos by status flags]:filter:_arb_where_filter' \
-                        '*:repo:($ws_repo_names)'
-                    ;;
                 help)
                     local -a help_completions=(
                         'filtering:Filter syntax for --where and --dirty'
@@ -598,7 +586,6 @@ _arb() {
                         'merge:Merge the base branch into feature branches'
                         'reset:Reset all repos to the share branch (or base if not pushed)'
                         'log:Show feature branch commits across repos'
-                        'diff:Show feature branch diff across repos'
                         'exec:Run a command in each repo'
                         'open:Open repos in an application'
                         'template:Manage workspace templates'