clavue-v1 1.1.0 → 1.3.0

package/README.md

@@ -35,6 +35,7 @@ Canonical primary command surfaces:
 - `/provider`: configure, switch, validate, repair, copy, edit, delete, or save provider profiles.
 - `/permissions` (`/approvals` compatibility alias): set the default permission mode so trusted development environments can run with less friction; use `/permissions autonomous` for an opt-in high-autonomy local development lane.
 - `/team`: inspect local team readiness, active team config, and capability state.
+- `/goal`: run a durable, evidence-gated goal loop with a persistent ledger and a bounded auto-continuation budget.
 - `/retro`: run a multi-round repo retrospective and upgrade loop.
 - `/tasks`: inspect task-board state for long-running work.
 - `/resume`: continue saved sessions.
@@ -64,8 +65,8 @@ npx -y clavue-v1
 Run a specific version with `npx`:
 
 ```bash
-npx -y clavue-v1@1.1.0 --version
-npx -y clavue-v1@1.1.0
+npx -y clavue-v1@1.3.0 --version
+npx -y clavue-v1@1.3.0
 ```
 
 Install globally from npm when you want the `clavue-v1` command to stay available:
@@ -87,9 +88,37 @@ curl -fsSL https://unpkg.com/clavue-v1/install.sh | bash
 Install a specific version globally:
 
 ```bash
-curl -fsSL https://unpkg.com/clavue-v1@1.1.0/install.sh | bash -s -- 1.1.0
+curl -fsSL https://unpkg.com/clavue-v1@1.3.0/install.sh | bash -s -- 1.3.0
 ```
 
+## Quick Start: Official Clavue Cloud
+
+Official mode is a provider profile, not a second runtime: the same tools,
+compaction, permissions, and route inspection as every custom-API profile —
+only the credential source and the model catalog differ.
+
+1. Run `clavue-v1 auth login` (or choose `使用 clavue OAuth` during first
+   launch), sign in at `www.clavue.com`, and approve the device code.
+2. Clavue stores the session as the `Clavue 官方` provider profile and activates
+   the official family automatically:
+
+```text
+主模型:   clavue-2.1        (official 27B coding model, 128K, premium pool)
+Haiku:    clavue-2.1-fast   (same model, fast pool — higher daily quota)
+Sonnet:   clavue-2.1-pro    (premium ceiling for planning and long-horizon work)
+Opus:     clavue-2.1-rev    (review-oriented; a different family from clavue-2.1, so it
+                             also works as CLAVUE_COMBO_REVIEW for cross-family review)
+```
+
+Manual fallback: create a member API key at `https://www.clavue.com/account`,
+then add the `Clavue 官方` preset in `clavue-v1 provider`.
+
+`auto` is also accepted. The CLI talks to `api.clavue.com/v1/messages`
+(Anthropic Messages-compatible protocol) and `/provider current` shows your plan and remaining
+points from the `x-clavue-points-*` response headers. Official identity is
+decided by exact host match only — a third-party gateway can never be
+mistaken for the official cloud.
+
 ## Quick Start: Custom API
 
 Fastest path for custom API users:
@@ -120,7 +149,8 @@ clavue-v1 provider doctor # diagnose source-of-truth, drift, validation, and nex
 clavue-v1 provider validate
 ```
 
-Use `clavue-v1 auth login` only if you want the official Anthropic login path. Custom API users do not need official login.
+`clavue-v1 auth login` is the clavue OAuth entry point. Custom API users can
+continue to use `clavue-v1 provider` without an OAuth login.
 
 ## First Useful Session
 
@@ -138,13 +168,13 @@ On first launch, Clavue should make the setup choice obvious:
 
 ```text
 请选择 API 配置模式:
-  使用官方登录
+  使用 clavue OAuth
   自定义 API 配置
   使用 CCR 代理
   跳过（稍后手动配置）
 ```
 
-- Use official login when you want the official Anthropic account flow.
+- Use clavue OAuth when you want the official Clavue membership flow.
 - Use custom API configuration when you have an API base URL plus API key or auth token.
 - Use CCR proxy when your environment already standardizes on a compatible proxy route.
 - Skip only when you want to configure later with `clavue-v1 provider` or `/provider`.
@@ -171,6 +201,55 @@ This package is intended for users who want an execution-first coding CLI with d
 
 On macOS, Clavue avoids Keychain by default and stores local credentials in `~/.clavue/.credentials.json` so startup does not trigger system Keychain prompts. If you explicitly want the old Keychain behavior back, launch with `CLAVUE_USE_KEYCHAIN=1 clavue-v1`.
 
+## Cross-Family Combo Review
+
+The review slot puts an independent model family between "the code changed"
+and "the work is done". Since 1.2.0 review is scheduled so it does not tax
+every edit:
+
+```bash
+CLAVUE_COMBO_MAIN=glm-5.3-flash          # developer model (any slot model is passed through verbatim)
+CLAVUE_COMBO_REVIEW=deepseek-v4-flash    # reviewer — pick a different family than main
+CLAVUE_COMBO_REVIEW_MODE=overlap         # overlap (default) | serial
+CLAVUE_COMBO_REVIEW_MIN_CHANGED_CHARS=80 # small edits accumulate; one review covers them
+CLAVUE_COMBO_REVIEW_MAX_PER_CHAIN=3      # review budget per query chain
+CLAVUE_COMBO_REVIEW_GRACE_MS=5000        # bounded wait for the final verdict at chain end
+CLAVUE_COMBO_REVIEW_FIX_LOOP=1           # opt-in: a chain-end "P0:" verdict grants one bounded fix turn
+```
+
+- `overlap` fires the review hop without blocking; the verdict is injected
+  at the next loop boundary so the developer model actually acts on it.
+  In the shipped A/B it roughly halves the review tax versus `serial`
+  (+38% vs +94% wall-clock on the hard task).
+- The reviewer is told which family wrote the code and which failure modes
+  that family is prone to. Same-family pairs still work; `/provider current`
+  flags them so you can choose an independent second opinion.
+- Review-on and the fix loop stay opt-in: on oracle-complete tasks a
+  competent developer model saturates on its own (see
+  `docs/evals/combo-review/`), so the defaults do not spend your time until
+  the discriminating experiment justifies it.
+
+## Subagent Model Matching
+
+Subagents (`Agent` tool, `/agents` definitions, `Explore`, `Plan`, teams) pick their model in this order:
+
+1. `CLAUDE_CODE_SUBAGENT_MODEL` (written by a provider profile's subagent slot) — an explicit global override that wins over everything.
+2. The `model` the caller or agent definition asked for:
+   - a combo slot name — `light`, `main`, `plan`, `review` — resolves to that `CLAVUE_COMBO_*` model verbatim; an unconfigured `light` falls back to `haiku`, the other slots to `inherit`;
+   - `haiku` is the fast tier: with `CLAVUE_COMBO_LIGHT` set it runs there (this is what `Explore` uses), otherwise it follows `ANTHROPIC_DEFAULT_HAIKU_MODEL`;
+   - `sonnet` / `opus` follow the parent's exact model when the parent is the same tier, else `ANTHROPIC_DEFAULT_*_MODEL`.
+3. `inherit` (the default) uses the parent conversation's model.
+
+Safety net for non-Claude routes: a bare tier alias that is not pinned by any of the variables above, on a gateway whose parent model is not a Claude model, inherits the parent instead of asking the route for a `claude-*` ID it cannot serve. Set `CLAVUE_COMBO_LIGHT` (or the `ANTHROPIC_DEFAULT_*_MODEL` pins that provider profiles write) to route tiers deliberately.
+
+```bash
+CLAVUE_COMBO_MAIN=deepseek-v4            # developer
+CLAVUE_COMBO_LIGHT=deepseek-v4-flash     # Explore / haiku-tier subagents / agents with `model: light`
+CLAVUE_COMBO_REVIEW=glm-5.3              # cross-family reviewer; agents with `model: review` run here too
+```
+
+The `/agents` wizard lists configured slots first and shows what each tier currently resolves to, so an agent can be pinned to "the fast slot" without knowing the underlying model ID. Parallel subagents run through the same concurrency-safe tool batching as every other tool (`CLAUDE_CODE_MAX_TOOL_USE_CONCURRENCY`, default 10); use `run_in_background` for independent work and foreground for results you need before continuing.
+
 ## Long-Running Session Memory
 
 Clavue automatically restarts normal long-running sessions with `--max-old-space-size=8192` before loading the full CLI. This prevents the common Node default ~4GB heap limit from killing large coding sessions with `Reached heap limit Allocation failed - JavaScript heap out of memory`.
@@ -191,7 +270,7 @@ Version check:
 
 ```bash
 npx -y clavue-v1 --version
-npx -y clavue-v1@1.1.0 --version
+npx -y clavue-v1@1.3.0 --version
 # available after a global install
 clavue-v1 --version
 ```
@@ -202,14 +281,28 @@ Provider/config entry point:
 clavue-v1 provider
 ```
 
-Anthropic account login/token commands:
+clavue OAuth:
 
 ```bash
 clavue-v1 auth login
-clavue-v1 setup-token
+clavue-v1 auth status --text
+clavue-v1 auth logout
 ```
 
-`clavue-v1 auth login` and `clavue-v1 setup-token` are only for Anthropic account auth flows. They are not the provider-profile entrypoint.
+The legacy Anthropic OAuth and long-lived `setup-token` flow are no longer
+user-facing login paths. Protocol-compatible API providers remain available
+through `clavue-v1 provider`.
+
+Canonical configuration names:
+
+```text
+~/.clavue/.clavue.json          global application state
+~/.clavue/settings.json         user settings
+<project>/.clavue/settings.json shared project settings
+<project>/.clavue/settings.local.json private project overrides
+<project>/clavue.md             project instructions
+<project>/clavue.local.md       private project instructions
+```
 
 ## In-Session Workflows
 
@@ -244,7 +337,22 @@ The Mao supervisor ledger is still used internally by delivery gates; user-facin
 
 Typing `agent teams` at the start of a prompt opens the same native `/team` flow instead of sending that phrase to the model as plain text. Agent teams are enabled by default in Clavue; set `CLAVUE_DISABLE_AGENT_TEAMS=1` or `CLAVUE_AGENT_TEAMS=0` before launch only if you need to disable them. Use `/team check` for a concrete readiness report.
 
-`/retro` runs a multi-round repo retrospective and upgrade loop guided by `PRODUCT.md` and `ARCHITECTURE.md`, with `tisheng.md` treated as historical context only when it still agrees.
+`/goal` turns a one-line objective into a durable mission. Clavue writes a ledger under `.clavue/goals/`, defines the plan itself, and keeps working across turns until evidence proves the objective, the budget runs out, or a real blocker appears. The loop is bounded: 20 auto-continued turns or 6 hours, whichever comes first. Exhaustion pauses the goal with an explicit `budget_exhausted` event; `/goal resume` grants a fresh budget. Completion is refused until at least one piece of evidence is on record, and starting a new goal supersedes the live one with an audit event.
+
+```text
+/goal ship the 1.3.0 release and verify npm, GitHub, and the website
+/goal criteria npm run check passes on main
+/goal evidence npm run test:fast passed (24 files)
+/goal status
+/goal pause waiting for the registry token
+/goal resume
+/goal complete release verified on npm and GitHub
+/goal stop superseded by hotfix
+```
+
+Only completed model turns advance the loop; `/goal status`, `/goal evidence`, and the other local subcommands never spend a turn or queue a duplicate mission prompt.
+
+`/retro` runs a multi-round repo retrospective and upgrade loop guided by `PRODUCT.md` and `ARCHITECTURE.md`, with `AGENTS.md` as the contributor contract and older planning notes under `docs/` treated as historical context only when they still agree. When a `/goal` is active, `/retro` treats that objective as the outer mission and records kept slices as goal evidence.
 
 ```text
 /retro
@@ -252,6 +360,16 @@ Typing `agent teams` at the start of a prompt opens the same native `/team` flow
 /retro onboarding and route validation
 ```
 
+`/review` reviews a pull request or local work with one rubric: findings anchored as `path:line`, severity markers `P0:`/`P1:`/`P2:`/`nit:` shared with the cross-family combo review hop, verified-vs-suspected labelling, and a single `Verdict:` line. With no argument it reviews the working tree when dirty, otherwise the current branch against its base.
+
+```text
+/review
+/review --staged
+/review --base origin/main
+/review 128
+/review 128 concurrency and error paths
+```
+
 Companion commands are still available and can either follow the current app provider or bind to a saved `/provider` profile independently.
 
 ```text