# Clavue World-Class Major Upgrade Plan - 2026-04-29

## Executive Decision

`v8.8.107` is a necessary stabilization release, not the end state. It fixed the observed `/init` regression, improved Cargo workspace guidance, and reduced avoidable clarification stalls for broad execute-now prompts. It did not prove that Clavue is already world-class across compatibility, stability, interaction logic, reliability, onboarding, provider routing, permissions, and release quality.

This document is the next major-version execution plan for Clavue. It adapts the operating model from `karpathy/autoresearch`: a human-authored program/spec controls the agents, work runs under fixed evaluation budgets, metrics are comparable across rounds, changes are kept only when evidence beats baseline, and multi-agent review is mandatory before release.

Reference: https://github.com/karpathy/autoresearch

## Non-Negotiable Goal

Clavue must become an execution-first AI coding CLI that is boringly reliable on the default path:

1. A new user installs Clavue and reaches a working coding session without confusion.
2. `/init` produces useful project guidance and marks onboarding complete only after success.
3. Broad Chinese or English "continue, fix, upgrade, solve everything" prompts execute safely instead of stalling on broad clarification.
4. Task boards reflect real work state, not stale planning artifacts.
5. Provider routing is explicit, testable, recoverable, and never silently misrepresents available capability.
6. Permission prompts are clear, safe, low-friction, and deterministic under policy.
7. Long sessions survive heap pressure, compaction, continuation, and resume.
8. Release pipelines are reproducible, automated, and independently verifiable from npm and fresh `npx`.

## Current Baseline

Released baseline:

- Version: `8.8.107`
- Commit: `a9f4dc6`
- npm latest: `8.8.107`
- Local gates passed before publish: `npm run check`, `npm run build`, 451 tests.
- Fresh install check passed from `/tmp`: `npx -y clavue@8.8.107 --version` -> `8.8.107 (Clavue)`.

Known unresolved issues:

- GitHub Actions release workflow is blocked by account billing or spending-limit, so trusted publishing is unavailable.
- The local global launcher can shadow fresh `npx` checks and return stale `8.8.106`.
- Task-board idle or stale-state behavior has policy coverage but still needs end-to-end session/UI regression tests.
- `/init` now has focused tests, but needs broader fixture coverage across real project types.
- Provider route quality is covered by unit tests, but needs a reproducible matrix and failure ledger.
- Permissions and onboarding need measured friction budgets, not only correctness tests.

## Operating Model

Use a Clavue-specific version of the `autoresearch` loop:

1. Write the plan in Markdown before implementation.
2. Establish a baseline metric before changing behavior.
3. Run fixed-budget rounds so results are comparable.
4. Change the smallest useful slice.
5. Run the same evaluation commands after the change.
6. Keep the change only if it improves or preserves the target metric without causing regressions.
7. Record the decision in an append-only ledger.
8. Require independent review for behavior, tests, release, and user experience.

Every round must produce:

- Hypothesis.
- Scope and non-goals.
- Owner.
- Fixed time or command budget.
- Target metric.
- Files touched.
- Verification commands.
- Result.
- Keep, discard, or retry decision.

## Fixed Evaluation Budgets

Use these budgets consistently. Do not expand a budget mid-round to hide failure.

| Loop | Budget | Purpose | Required Output |
| --- | ---: | --- | --- |
| Triage scan | 20 minutes | Identify one concrete failure mode | One hypothesis and smallest target |
| Design slice | 30 minutes | Write implementation contract | Files, tests, acceptance criteria |
| Implementation slice | 90 minutes | Make one bounded change | Patch plus focused tests |
| Focused eval | 20 minutes | Prove the slice works | Targeted test output |
| Full local gate | 120 minutes | Prove no repo regression | `npm run check`, `npm run build` |
| Release verification | 45 minutes | Prove install and publish path | npm, npx, tag, workflow evidence |
| Post-release audit | 30 minutes | Prove user path works after publish | Fresh cache/global/version checks |

## Primary Metrics

Track these metrics in `docs/evals/world-class/results.tsv` once the harness exists.

| Metric | Target | Evidence |
| --- | ---: | --- |
| `default_path_pass_rate` | 100% | Install -> provider -> `/init` -> edit -> test -> final |
| `init_success_rate` | 100% | Fixture matrix for Node, Rust, Python, Go, monorepo, docs-only |
| `continuation_no_stall_rate` | >= 98% | Broad zh/en execute-now prompts avoid unnecessary clarification |
| `task_board_truth_rate` | >= 99% | No stale in-progress task after pivot or completion |
| `provider_route_matrix_pass_rate` | 100% | Anthropic, OpenAI-compatible, Codex/GPT, degraded, blocked |
| `permission_decision_accuracy` | >= 99% | Safe allow, explicit ask, deny, shell-rule precedence |
| `long_session_recovery_rate` | 100% | Heap, compaction, prompt-too-long, resume, memory recall |
| `release_reproducibility_rate` | 100% | Clean dist rebuild and package dry-run |
| `fresh_install_version_match` | 100% | Fresh `npx` and tarball binary match package version |
| `trusted_publish_success_rate` | 100% | GitHub Actions release workflow completes |

## Required Ledgers

Create and maintain these append-only files:

- `docs/evals/world-class/results.tsv`
- `docs/evals/world-class/keep-discard-ledger.md`
- `docs/evals/world-class/release-ledger.md`
- `docs/evals/world-class/provider-route-ledger.md`
- `docs/evals/world-class/onboarding-friction-ledger.md`

`results.tsv` header:

```tsv
date	round	owner	area	hypothesis	baseline_metric	result_metric	commands	decision	commit
```

Keep/discard entry template:

```md
## Round <id> - <area> - <date>

Hypothesis:
Baseline:
Change:
Commands:
Result:
Decision: keep | discard | retry
Reason:
Follow-up:
```

## Multi-Agent Review Roles

Use multiple agents only when the work can be split without conflict.

| Role | Authority | Must Produce |
| --- | --- | --- |
| Clavue lead executor | Owns implementation | Patch, focused tests, local verification |
| Codex reviewer | Independent critique | Bugs, missing tests, release risks |
| UX reviewer | Interaction logic and onboarding | Friction report, prompt/session edge cases |
| Provider reviewer | Routing and compatibility | Route matrix result and degraded-mode evidence |
| Permission reviewer | Safety and low-friction policy | Rule precedence and prompt clarity evidence |
| Release operator | Packaging and npm/GitHub path | Tag, workflow, npm, npx, tarball verification |

Rule: reviewers do not approve by opinion. They approve by evidence tied to the metrics above.

## Workstream 1 - `/init` And Onboarding

Problem:

`/init` is a trust gateway. If it fails, users assume the whole product is unreliable.

Required upgrades:

- Expand `/init` fixture matrix: Node package, Cargo single crate, Cargo workspace, Python `pyproject`, Go module, Makefile, nested app, docs-only repo, mixed monorepo.
- Verify generated `clavue.md` contains useful commands and project facts.
- Verify onboarding state changes only after successful create or refresh.
- Add failure tests for unwritable target, malformed manifests, ambiguous nested projects, and existing stale guidance.
- Add a smoke command that creates a temp project, runs `/init`, reads `clavue.md`, and checks onboarding config.

Acceptance gates:

- `node --test tests/init-command.test.mjs`
- New fixture tests pass.
- `npm run check`
- Fresh packaged CLI can run `/init` smoke from a temp directory.

Keep criteria:

- `init_success_rate = 100%`.
- No false onboarding-complete state after failed write.

## Workstream 2 - Task Board And Continuation Truth

Problem:

The screenshot showed idle prompt state while the task board still displayed pending and in-progress work after a pivot. That is not a terminal freeze, but it is a product trust failure.

Required upgrades:

- Define task-board truth invariants:
  - No stale `in_progress` task when the assistant has stopped and the current prompt is idle.
  - Execute-now pivots supersede broad planning tasks.
  - Clarification questions must either pause all active tasks or mark the blocked task explicitly.
  - Completed tasks must not remain visually pending after successful release or verification.
- Add tests around continuation prompts: `继续`, `很好继续`, `持续开发到全部结束`, `fix everything`, `continue`.
- Add tests for ask-clarification policy:
  - Broad strategic menu questions are disallowed when safe default execution is available.
  - Clarification is allowed only for destructive risk, missing access, or a real product decision.
- Add UI/session regression coverage for task-board rendering after pivot, completion, and failed command.

Acceptance gates:

- `node --test tests/user-turn-intent.test.mjs`
- `node --test tests/session-workflow-continuity.test.mjs`
- New task-board regression test.
- Manual or scripted TUI screenshot smoke for idle board state.

Keep criteria:

- `continuation_no_stall_rate >= 98%`.
- `task_board_truth_rate >= 99%`.

## Workstream 3 - Provider Routing Reliability

Problem:

Provider flexibility is a core Clavue advantage, but route ambiguity can break tools, permissions, or user expectations.

Required upgrades:

- Build a provider matrix with these states:
  - Official Anthropic route.
  - OpenAI-compatible Responses route.
  - GPT/Codex route with compatible tools.
  - Chat-only route.
  - Degraded partial-native route.
  - Blocked route.
  - Missing credentials.
  - Legacy config migration.
- Make `/provider doctor` produce a deterministic next action for every matrix row.
- Ensure model-slot blanks inherit provider defaults safely.
- Ensure route-visible tool filtering never hides direct repo tools when direct tools are actually available.
- Add failure ledgers for route probes.

Acceptance gates:

- `node --test tests/provider-runtime-core.test.mjs`
- `node --test tests/provider-control-text.test.mjs`
- `node --test tests/provider-cli.test.mjs`
- `npm run verify:provider:smoke`
- `npm run test:route-policy`

Keep criteria:

- `provider_route_matrix_pass_rate = 100%`.
- No route can claim native workflow capability without validation evidence.

## Workstream 4 - Permissions And Safety

Problem:

World-class permission UX must be safe and low-friction. It cannot be a confusing stream of prompts or a dangerous bypass.

Required upgrades:

- Define permission modes in user language and implementation language.
- Add tests for shell rule precedence: explicit deny, explicit ask, safe local allow, classifier fallback.
- Add tests for path permissions across `.clavue`, project files, nested workspaces, generated artifacts, and outside-repo paths.
- Add a "why am I being asked?" explanation check for common permission prompts.
- Audit auto mode eligibility against provider route capability.
- Add a recent-denial recovery path: the user should know the smallest safe permission to grant.

Acceptance gates:

- `node --test tests/permission-authorization-flow.test.mjs`
- Existing safe-local bash and permission tests.
- Manual prompt copy review for bash, file write, file edit, filesystem, web fetch, sandbox.

Keep criteria:

- `permission_decision_accuracy >= 99%`.
- No broad permission suggestion when a scoped suggestion is available.

## Workstream 5 - Stability And Long-Session Recovery

Problem:

Clavue must survive real work: long sessions, high memory, compact/resume, provider failures, and partial tool outputs.

Required upgrades:

- Expand heap tests around default Node versions and explicit `NODE_OPTIONS`.
- Add prompt-too-long recovery integration tests with latest-turn preservation.
- Add compaction tests for stale plan removal and current task preservation.
- Add background task output cap tests for long logs.
- Add stuck-command timeout and cancellation smoke.
- Add memory relevance tests for Chinese continuation prompts and stale memories.

Acceptance gates:

- `node --test tests/node-heap-bootstrap.test.mjs tests/heap-pressure.test.mjs`
- `node --test tests/session-workflow-continuity.test.mjs`
- Existing compaction and memory tests.
- Long-session smoke: scripted 20-turn temp repo workflow.

Keep criteria:

- `long_session_recovery_rate = 100%`.
- No critical continuity field is lost after compaction or resume.

## Workstream 6 - Compatibility Matrix

Problem:

Compatibility cannot be claimed from one macOS machine.

Required upgrades:

- Node versions: 18, 20, 24, current local.
- OS targets: macOS arm64, macOS x64 if available, Linux x64, Linux arm64, Windows package smoke where possible.
- Shells: zsh, bash, non-interactive CI shell.
- Project types: Node, Rust, Python, Go, monorepo, docs-only.
- Terminal modes: normal interactive, headless `-p`, non-interactive provider commands.
- Package paths: global install, `npx`, tarball extraction, local `node dist/cli.js`.

Acceptance gates:

- CI matrix passes once GitHub Actions billing is repaired.
- Local package tarball extraction smoke passes.
- Fresh `npx` from `/tmp` with isolated cache passes.
- Global launcher stale-version detection is documented and tested.

Keep criteria:

- `default_path_pass_rate = 100%` across supported environments.

## Workstream 7 - Release Pipeline

Problem:

The `v8.8.107` trusted release workflow failed before execution because GitHub Actions could not start due to billing or spending-limit. Local npm publish was acceptable as fallback, but it is not world-class as the primary path.

Required upgrades:

- Repair GitHub Actions billing/spending-limit issue.
- Re-run `Release Clavue` workflow for the next tag and require success.
- Add a preflight command that checks:
  - GitHub Actions availability.
  - npm login state.
  - package version/tag alignment.
  - existing npm version conflict.
  - local global launcher version shadowing.
  - fresh `npx` cache path.
- Add a release checklist that distinguishes:
  - Source verification.
  - Dist reproducibility.
  - Package preview.
  - Trusted publish.
  - Local fallback publish.
  - Fresh install verification.
  - Public GitHub release verification.

Acceptance gates:

- `npm run check`
- `npm run build`
- `npm run package:release`
- GitHub workflow success for the tag.
- `npm view clavue version`
- `NPM_CONFIG_CACHE=/tmp/clavue-fresh-npx-cache npx -y clavue@<version> --version`
- Downloaded tarball `node package/dist/cli.js --version`

Keep criteria:

- `release_reproducibility_rate = 100%`.
- `trusted_publish_success_rate = 100%`.
- No release is considered complete if only local machine state was verified.

## Workstream 8 - Install And Upgrade UX

Problem:

The local machine had `/opt/homebrew/bin/clavue` returning `8.8.106` while npm had `8.8.107`. This is an upgrade-path trust issue.

Required upgrades:

- Add `clavue doctor` or existing doctor output that detects:
  - npm latest version.
  - current binary path.
  - current binary version.
  - global install manager.
  - stale launcher.
  - suggested exact repair command.
- Add docs for global, npx, install script, and native launcher paths.
- Add a smoke that verifies `which clavue`, `clavue --version`, `npx`, and tarball binary.

Acceptance gates:

- Upgrade-path tests.
- README install section matches package version.
- `validate-release.mjs` catches stale version references.

Keep criteria:

- `fresh_install_version_match = 100%`.
- Stale global launcher is reported with a clear repair action.

## Workstream 9 - Documentation And Product Truth

Problem:

Clavue should not depend on vague claims. Product truth must say what works, what is degraded, and how to recover.

Required upgrades:

- Update product docs to classify:
  - Fully supported.
  - Supported with degraded behavior.
  - Experimental.
  - Not supported.
- Add "known failure recovery" docs for `/init`, provider setup, stale launcher, release workflow, permissions, and long session compaction.
- Keep Clavue identity clear: provider routing is a capability, not the product identity.
- Add a public-quality release note template with user-visible fixes, tests run, and known limitations.

Acceptance gates:

- `node --test tests/product-truth-surfaces.test.mjs`
- `node scripts/validate-release.mjs`
- Manual docs review against current package behavior.

Keep criteria:

- No docs claim a capability without a test, smoke, or explicit limitation.

## Workstream 10 - Security And Privacy

Problem:

Provider keys, auth tokens, session data, and permission state are trust-critical.

Required upgrades:

- Audit secret redaction in debug, subprocess, provider, and release logs.
- Ensure `.clavue`, legacy `.claude`, memory, and local auth state are never packaged or committed.
- Add tests for provider credential migration without plaintext leaks.
- Add permission copy that names trust boundary and scope.
- Add release check for accidental token-like strings in published package.

Acceptance gates:

- Existing redact/subprocess credential tests.
- `npm pack --dry-run` surface review.
- New secret scan over publishable files.

Keep criteria:

- No credential or local runtime file enters `git`, npm package, or release artifacts.

## Implementation Phases

### Phase 0 - Freeze And Baseline

Goal: make current quality measurable.

Tasks:

- Record `v8.8.107` as baseline in `results.tsv`.
- Record GitHub Actions billing failure in `release-ledger.md`.
- Record stale global launcher finding in `onboarding-friction-ledger.md`.
- Run `npm run campaign:world-class`.
- Run `npm run check`.
- Run `npm run build`.

Exit criteria:

- Baseline ledgers exist.
- Baseline command outputs are recorded.

### Phase 1 - Eval Harness

Goal: make world-class claims testable.

Tasks:

- Add `scripts/run-world-class-evals.mjs` or extend `run-campaign-round.mjs`.
- Emit JSON and TSV summaries.
- Add fixture directories for `/init` and install smoke tests.
- Add release preflight script.
- Add task-board regression harness if current tests cannot observe the UI state.

Exit criteria:

- A single command produces the world-class scorecard.
- Failing metrics point to exact workstream owners.

### Phase 2 - Critical UX Regressions

Goal: eliminate the visible trust failures.

Tasks:

- Finish task-board truth invariants.
- Add execute-now pivot cleanup.
- Add stale in-progress task detection.
- Add `/init` matrix fixtures.
- Add stale launcher detection.

Exit criteria:

- The screenshot class cannot recur without a failing test.
- `/init` failure or success state is deterministic.

### Phase 3 - Provider And Permission Hardening

Goal: make powerful routes safe and predictable.

Tasks:

- Build provider route matrix.
- Strengthen `/provider doctor` next actions.
- Audit route-visible tool filtering.
- Strengthen permission precedence tests.
- Improve prompt explanations for scoped permission grants.

Exit criteria:

- Provider and permission metrics meet targets.
- No broad permission or route claim is made without evidence.

### Phase 4 - Reliability And Compatibility

Goal: prove Clavue survives long real sessions and varied environments.

Tasks:

- Add long-session smoke.
- Add compaction/resume stress fixtures.
- Add cross-version Node checks locally or in CI.
- Add tarball extraction smoke.
- Add headless and interactive command compatibility checks.

Exit criteria:

- Reliability metrics meet targets.
- CI matrix is green after billing repair.

### Phase 5 - Release System Repair

Goal: return to trusted publishing as primary release path.

Tasks:

- Fix GitHub billing/spending-limit.
- Re-run release workflow.
- Add release preflight.
- Add post-release verifier.
- Document local fallback as emergency-only.

Exit criteria:

- Next release publishes through GitHub Actions.
- npm, fresh `npx`, tarball, global binary, and public release evidence all match.

### Phase 6 - Major Release Candidate

Goal: ship a major-quality version only after evidence is complete.

Tasks:

- Run all workstream gates.
- Run multi-agent review.
- Produce release candidate notes.
- Run fresh install from clean temp cache.
- Run upgrade test from previous global version.
- Confirm no unrelated untracked docs or artifacts enter release.

Exit criteria:

- All primary metrics meet target.
- All ledgers have keep/discard decisions.
- Release operator signs off with exact command evidence.

## Concrete Backlog

| Priority | Area | Target | Suggested Files | Required Tests |
| --- | --- | --- | --- | --- |
| P0 | Release | Repair GitHub Actions billing blockage | GitHub settings, `.github/workflows/release.yml` if needed | Release workflow success |
| P0 | Upgrade UX | Detect stale global launcher | `src/screens/Doctor.tsx`, `src/cli/update.ts`, tests | New upgrade-path test |
| P0 | Task board | Remove stale tasks after execute/debug pivot | `src/tasks.ts`, `src/components/tasks/*`, intent/continuity code | New task-board regression |
| P0 | `/init` | Add full project fixture matrix | `src/commands/init.ts`, `tests/init-command.test.mjs` | Fixture matrix |
| P1 | Provider | Route matrix and doctor next actions | `src/utils/providerRuntimeCore.js`, provider command files | Provider CLI/runtime tests |
| P1 | Permissions | Scoped recovery and rule precedence | `src/utils/permissions/*`, permission components | Permission flow tests |
| P1 | Long sessions | 20-turn smoke and compaction checks | continuity, compaction, memory tests | Long-session smoke |
| P1 | Release | Preflight and post-release verifier | `scripts/*release*.mjs`, package scripts | Release-pipeline tests |
| P2 | Docs | Known failure recovery guide | `README.md`, `docs/*` | Product truth tests |
| P2 | Security | Publish surface secret scan | `scripts/validate-release.mjs` or new script | Release validation |

## Release Readiness Checklist

Do not ship a major release unless every item is checked.

- `git status --short` contains only intended tracked changes and approved untracked files.
- `npm run campaign:world-class` passes.
- `npm run check` passes.
- `npm run build` passes.
- `npm run package:release` passes when release artifacts matter.
- `node dist/cli.js --version` matches package version.
- Fresh `npx` from `/tmp` with isolated cache matches package version.
- Downloaded npm tarball binary matches package version.
- Global launcher path and version are checked.
- GitHub Actions release workflow succeeds.
- npm `latest` points to the release version.
- Public release artifacts are uploaded or explicitly marked unavailable.
- Ledgers contain keep/discard entries for every material change.
- Reviewer findings are either fixed or documented as accepted risk.

## Definition Of Done

This upgrade is complete only when:

1. All P0 and P1 workstreams meet their target metrics.
2. A fresh user can install, configure provider, run `/init`, edit code, run tests, continue after interruption, and upgrade without manual rescue.
3. The release pipeline succeeds through trusted publishing.
4. Every major capability claim has a test, smoke, or explicit limitation.
5. The next release can be verified independently from npm, GitHub, local tarball, and clean `npx`.

Until then, Clavue should be described as improving toward world-class reliability, not as already finished.
