# docs: minimize entire review documentation

## Sessions

## Changes

- MCLAUDE.md+2/-4
- docs/architecture

- Mreview-command.md+43/-247

### `entire review` Command

`entire review` runs a set of configured review skills inside an agent session. The review session is an immutable fact attached to a checkpoint — no verdict, no status tracking, no empty commits. On the next `git commit`, the review session is condensed into the checkpoint metadata alongside normal sessions, permanently recording that the code was reviewed and which skills were run.
`entire review` runs a configured review profile. Keep documentation brief and user-facing.

Configured per-agent in `.entire/settings.json` (`EntireSettings.Review`); launchable agents (claude-code, codex, gemini-cli) receive `ENTIRE_REVIEW_*` env vars that the `UserPromptSubmit` hook reads to tag the session as `Kind = "agent_review"`. Multi-agent runs use a TUI dashboard + opt-in cross-agent synthesis.

See [Review Command](docs/architecture/review-command.md) for the full command surface, settings schema, env-var handshake, multi-agent UI, anti-features (do NOT recreate), and key-file map.
See [Review Command](docs/architecture/review-command.md) for usage, minimal profile config, and key files.

# Important Notes

# `entire review` Command
# `entire review`

`entire review` runs a named review profile. A profile defines one canonical task (for example `general`, `security`, or `accessibility`), a set of **reviewer** agents that all run that task, and a single **judge** that consolidates the reviewers' reports into the final verdict in a closing round. Reviewer sessions are immutable facts attached to checkpoints; the final verdict is stored locally in the review manifest for findings/fix workflows. Experimental review command for running one configured review profile.

## Command Surface
## Basic use

```sh
entire review --configure       # create or edit a profile
entire review --list            # list profiles
entire review <profile>         # run a profile
entire review --profile <name>  # same as positional form
entire review --agent <name>    # run one reviewer from the profile
entire review --findings        # view local findings
```
entire review                          # Interactive: pick a profile to run. Non-interactive: list profiles + error
entire review security                 # Run a named profile
entire review --profile accessibility  # Same, flag form
entire review --list                   # List configured profiles (reviewers + judge), marking the default
entire review --configure                    # Interactive: guided wizard. Non-interactive: list agents + profiles
entire review --configure --profile general --set-agents claude-code,codex --set-judge claude-code --set-output trail
                                               # Configure a profile non-interactively (no TUI)
entire review --configure --profile sec --set-slot claude-code=opus --set-slot codex --set-judge claude-code=opus
entire review --configure --profile general --set-model codex=gpt-5-codex --set-task "..."
entire review --edit --profile general       # Advanced skill-level config (skill picker)
entire review --agent <name>           # Run one reviewer from the selected profile
entire review --agent <name> --model <model>  # Override that reviewer's model for this run
entire review --agents                 # List the profile's reviewers (valid --agent values)
entire review --models                 # List models each agent advertises
entire review --models --agent codex   # ...filtered to one agent
entire review --prompt "focus on auth" # Add one-off instructions
entire review --timeout 15m            # Per-reviewer timeout (default 10m)
entire review --findings               # Browse local review findings

Useful run flags:

```sh
entire review --prompt "focus on auth"
entire review --timeout 15m
entire review --agent claude-code --model opus
```

A bare `entire review` never silently runs a default crew. In an interactive terminal it opens a chooser listing the configured profiles (default pre-selected); in a non-interactive context it prints the profiles and exits with an error so automation must name a profile explicitly. To tag an already-finished session as a review after the fact, use
`entire attach --review <session-id>` (the old `entire review attach` subcommand was removed).

## Profiles

When no profiles are configured, interactive `entire review` runs a guided setup: choose a review focus (or `Custom…` to write the task), build the reviewer crew (a single-screen add/edit/remove slot list seeded with all launchable agents — the same agent may appear more than once on different or identical models), then choose the judge that consolidates their reports, and finally where the verdict should go (local or the branch's trail). It saves the profile and asks before starting agents.
Profiles live in:

`entire review --configure` is the configuration entry point:
- With `--set-agents` / `--set-slot` / `--set-judge` / `--set-output` /
  `--set-task` / `--set-model agent=model`, it writes the profile
  non-interactively (no TUI).
  `--set-*` writes preserve profile-level fields the flags don't touch (custom
  `task`, etc.).
- With no `--set-*` flags in an interactive terminal, it opens the guided
  wizard (which already lists the selectable agents).
- With no `--set-*` flags in a non-interactive context, it prints the discovery
  view: the **available review agents** (those with review-runner adapters,
  marking which have hooks installed) and the **currently configured profiles**,
  plus an example `--set-*` command. Defaults are intentionally simple:
  Claude/Codex use `/review`, Gemini uses the profile task directly, and Claude
  is preferred as the default judge when available.
- `.entire/settings.json` for shared project config
- `.entire/settings.local.json` for local, git-ignored config

When two or more adapter-backed reviewers are configured and `--agent` is not
set, `entire review` fans out to all configured reviewers. There is no per-run
multi-picker: the profile is the fan-out contract. Multi-reviewer profiles
resolve one judge (explicit, or auto-selected from the reviewers); the judge
runs after the reviewers finish and produces the final verdict.
A profile contains:

## Settings Schema
- `task`: what to review for
- `agents`: reviewer slots
- `judge`: optional final consolidating reviewer
- `output`: `local` or `trail`

Profiles are configured under `review_profiles` in either the shared project
settings (`.entire/settings.json`, committed) or the per-developer override
(`.entire/settings.local.json`, git-ignored). Guided setup and `--configure`
let the user pick the destination (`--local` for the scripted path); the
non-interactive first run writes the project file. The two layers (plus legacy
clone-local preferences) are **merged per profile name** by `settings.Load`, so
a team can share profiles in the project file while individuals add or override
profiles locally without hiding the shared set. Schema:
Minimal example:

```json
{
  "security": {
    "task": "Review this change for auth, injection, secrets, and privilege-boundary bugs.",
    "agents": {
      "claude-sonnet": {"agent": "claude-code", "model": "sonnet", "skills": ["/security-review"]},
      "codex": {"model": "gpt-5-codex", "skills": ["/review"], "prompt": "Focus on security."}
    },
    "judge": {"agent": "claude-code", "model": "opus"},
    "output": "local"
  }
}
```

- The profile-level `task` is the shared work item.
- Each `agents` map entry is an **reviewer** id. For simple entries the id is
  the agent name; to run the same agent more than once, use aliases and set
  `agent` plus `model`. Per-reviewer `skills`, `prompt`, and `model` adapt the
  task to agent-specific mechanics.
- `judge` is the single agent (+ optional model) that consolidates the
  reviewers' reports into the final verdict. It need not be one of the
  reviewers. It is optional: a one-reviewer profile needs none, and a
  multi-reviewer profile with no judge set auto-selects a text-gen-capable
  reviewer (preferring claude-code, then codex, then gemini).
- `output` selects where the verdict is delivered: `local` (printed and saved
to the local review manifest — the default; omitted from settings) or `trail`
(additionally posted to the branch's trail as a finding via the data API).
  Resolved by `profileOutput`; the trail post is wired through the injected
  `Deps.PostReviewToTrail` hook (`review_bridge.go` → `createTrailReviewFinding`).

## Behavior

`entire review --models` lists the models each agent advertises via the
optional `agent.ModelLister` capability (`cmd/entire/cli/agent/model_lister.go`).
Only claude-code advertises a list (its curated, real aliases opus/sonnet/haiku).
Agents whose CLI has no enumeration command (codex, gemini) do not implement
`ListModels`; the picker offers only Default + Custom for them, and `--models`
notes there are none. The `--model` flag still forwards any value the agent CLI
accepts.
- Reviewers run the profile task.
- Multi-reviewer profiles run reviewers concurrently, then run one judge.
- Results are printed and saved locally; `output: "trail"` also posts findings to the branch trail.
- A bare non-interactive `entire review` does not auto-run a profile. Automation should pass a profile name.

Settings fields: `EntireSettings.ReviewProfiles` and
`EntireSettings.ReviewDefaultProfile` in `cmd/entire/cli/settings/settings.go`.

## Key files

## How It Works (env-var handshake)

1. `entire review` resolves a profile (positional/`--profile`, else the
   interactive chooser, else — non-interactively — an error). It composes
   reviewer prompts via `review.ComposeReviewPrompt` and computes scope
   (mainline base ref via `review.ComputeScopeStats`, overridable with `--base`).
2. **For agents with review-runner adapters** (claude-code, codex, gemini-cli):
   the spawned process is given env vars
   `ENTIRE_REVIEW_{SESSION,AGENT,SKILLS,PROMPT,STARTING_SHA}` that the agent's
   `UserPromptSubmit` lifecycle hook reads to tag the session as
   `Kind = "agent_review"` with the configured skills/prompt. Each spawned
   process has its own env, so multiple worktrees and multi-agent runs are
   correct by construction (no shared marker file, no race).
3. **For agents without review-runner adapters yet**: `RunMarkerFallback` writes
a `PendingReviewMarker` file and prints guidance — the user opens the agent
themselves and runs the skills, then tags it with `entire attach --review`.
4. Reviewers run the selected profile's task; each session ends naturally.
5. In multi-reviewer profiles, the judge runs after reviewers finish (see
   Multi-Agent UI). It receives all reviewer reports and consolidates them into
the final verdict.
6. On the next `git commit`, the PostCommit hook condenses reviewer sessions
   into the checkpoint on `entire/checkpoints/v1`, with `Kind`, `ReviewSkills`,
   and `ReviewPrompt` recorded in `CommittedMetadata`.
7. The `CheckpointSummary` sets `HasReview = true` for O(1) lookup. `HasReview`
   is an umbrella "any review happened" flag.
8. `entire status` and the re-run guard read `HasReview` from the checkpoint
   metadata (no commit history walking).

## Checkpoint Metadata

Review metadata is stored at two levels on `entire/checkpoints/v1`:

- **`CommittedMetadata` (per-session)**: `kind: "agent_review"`, `review_skills:
  ["/skill1", "/skill2"]`, `review_prompt: "..."`
- **`CheckpointSummary` (per-checkpoint)**: `has_review: true` (umbrella; set
  when any session in the checkpoint has a review-kind `Kind`)

## Architecture

- **`AgentReviewer` interface** (`cmd/entire/cli/review/types/reviewer.go`):
  per-agent contract with `Name() string` and `Start(ctx, RunConfig)
  (Process, error)`. Each adapter-backed reviewer implements this in its own
  package.
- **`ReviewerTemplate`** (`cmd/entire/cli/review/types/template.go`): shared
  scaffolding (spawn → pipe stdout → run parser → forward events → close +
  bounded stderr capture). Each agent supplies only its `BuildCmd` (argv/env)
  and `Parser` (stdout-to-Event stream).
- **`Sink` interface**: consumers of the event stream. Production sinks:
  `DumpSink` (post-run per-agent narrative), `TUISink` (Bubble Tea live
dashboard), `SynthesisSink` (final verdict). Composed by
  `composeMultiAgentSinks` based on TTY detection.
- **`Run` / `RunMulti`** (`run.go`, `run_multi.go`): single- and N-agent
  orchestrators. In `RunMulti` each reviewer runs concurrently in its own
  goroutine; events fan into a single dispatch loop so the serial-dispatch
  contract holds. Per-reviewer skills/prompts are injected via
  `perAgentConfiguredReviewer`.
- **Per-reviewer timeout** (`run.go`): each reviewer is started under its own
  `context.WithTimeout` (`RunConfig.ReviewerTimeout`, default
  `defaultReviewerTimeout` = 10m, overridable with `--timeout`). When an
  reviewer's deadline elapses while the run is still live, its process is
  cancelled (killed) and it is marked failed-by-timeout; siblings and the judge
  proceed. A parent-context cancellation (Ctrl+C) is classified as cancelled
  instead. The judge has its own separate `defaultSynthesisProviderTimeout` (2m).
- **Judge resolution** (`profile.go`): `profileJudge` returns the explicitly
  configured judge (`judge`); `resolveJudge` falls back to `defaultJudge`, which
  auto-selects a text-gen-capable reviewer (preferring claude-code, then codex,
  then gemini) when none is set.
- **Synthesis** (`synthesis_sink.go`): the single judge is an
  `AgentSynthesisProvider` consumed by `SynthesisSink`. It receives all
  reviewer narratives and writes one verdict; provider failure surfaces as
  "final report unavailable".
- **Env-var contract** (`env.go`): single source of truth for `ENTIRE_REVIEW_*`.
- **Scope detection** (`scope.go`): first existing of
  `origin/HEAD → origin/main → origin/master → main → master`, overridable via
  `--base <ref>` (validated through go-git's `ResolveRevision`).

## Multi-Agent UI

When `RunMulti` is dispatched in a TTY, the sink slice is
`[TUISink, DumpSink, SynthesisSink]`:

- **`TUISink` / `reviewTUIModel`**: live dashboard with one row per reviewer;
  `Ctrl+O` drills into an agent's full event buffer; `Ctrl+C` cancels via the
  shared `CancelFunc`. `RunFinished` blocks on dismissal so `DumpSink` renders
  below rather than overlapping.
- **`SynthesisSink`** (`synthesis_sink.go`): after the dump it composes an
  adjudication prompt from all reviewer narratives + per-run prompt + profile
task and calls its `SynthesisProvider` — an `AgentSynthesisProvider` for the
  resolved judge. Skipped when cancelled or fewer than 2 reviewers produced
  usable output. Provider failures degrade gracefully.
- **Sink composition** (`composeMultiAgentSinks` in `cmd.go`): pure helper
taking explicit `isTTY`/`canPrompt` so tests don't depend on real TTY
detection.

## Skill Discovery (Claude Code)

`DiscoverReviewSkills` (`cmd/entire/cli/agent/claudecode/discovery.go`) walks
three roots: plugin cache, user skills (`~/.claude/skills`), and user
commands/agents. `pickLatestVersion` picks ONE version directory per plugin
(highest valid semver, else lexicographic max) to avoid duplicate skill entries.

## Anti-Features (do NOT recreate)

- `PendingReviewMarker` for adapter-backed reviewers (env-var handshake makes
  it unnecessary; the marker only backs the manual-attach fallback)
- `WorktreePath`-style marker scoping / `AgentEntries` map (env per process)
- Marker overwrite tripwire / refuse-attach guard
- `--track-only` / `--postreview` / `--finalize` / empty review commits
- `Launcher` + `HeadlessLauncher` as separate interfaces (single `AgentReviewer`)
- Agent-specific stdout post-processing in shared multi-agent code (per-agent
  parsers own their format; shared code only sees `Event` variants)
- Fabricated "example" model lists for agents without an enumeration command
  (codex/gemini advertise nothing; Default + Custom only)
- A "master" worker slot that both reviews and adjudicates in one pass (the
  judge is a separate consolidation round, even when auto-selected from the
  reviewers)

## Key Files

- `cmd/entire/cli/review/cmd.go` — `NewCommand()`, `runReview` dispatch fork,
  `runReviewListProfiles` (`--list`), judge wiring, `composeMultiAgentSinks`
- `cmd/entire/cli/review/picker.go` — guided setup, focus picker (presets +
  custom task), `pickSlotList` (reviewers), `promptForJudge`, profile chooser
- `cmd/entire/cli/review/profile.go` — profile resolution, `profileJudge` /
  `resolveJudge` / `defaultJudge`, default tasks
- `cmd/entire/cli/review/synthesis_sink.go` / `synthesis_prompt.go` — final
  verdict sink + adjudication prompt
- `cmd/entire/cli/review/marker_fallback.go` — manual fallback for agents
  without review-runner adapters
- `cmd/entire/cli/review/prompt.go` / `scope.go` / `run.go` / `dump.go` /
  `run_multi.go` — core machinery
- `cmd/entire/cli/review/tui_sink.go` / `tui_model.go` / `tui_detail.go` — TUI
- `cmd/entire/cli/review/types/{reviewer,sink,template}.go` — interface contracts
- `cmd/entire/cli/review/env.go` — `ENTIRE_REVIEW_*` constants + skills codec
- `cmd/entire/cli/agent/{claudecode,codex,geminicli}/reviewer.go` — per-agent
  `AgentReviewer` implementations
- `cmd/entire/cli/agent/claudecode/models.go` — the only `ModelLister` (real
  Claude aliases)
- `cmd/entire/cli/lifecycle.go` — `adoptReviewEnv` reads `ENTIRE_REVIEW_*`
- `cmd/entire/cli/review_bridge.go` — `launchableReviewerFor`,
  `headHasReviewCheckpoint`
- `cmd/entire/cli/attach.go` — `entire attach --review` (post-hoc tagging;
  consumes a pending-review marker)
- `cmd/entire/cli/settings/settings.go` — `ReviewProfileConfig` (`Agents`,
  `Judge`)
- `cmd/entire/cli/review/cmd.go`
- `cmd/entire/cli/review/picker.go`
- `cmd/entire/cli/review/profile.go`
- `cmd/entire/cli/review/run.go`
- `cmd/entire/cli/review/run_multi.go`
- `cmd/entire/cli/review/synthesis_sink.go`
- `cmd/entire/cli/review_bridge.go`
- `cmd/entire/cli/settings/settings.go`