# Clavue v8.9 Upgrade Plan - Product Maturity Pass

Date: 2026-04-30

Current local package version: `8.8.108`

This plan is a follow-up to `docs/clavue-world-class-major-upgrade-plan-2026-04-29.md`. The earlier plan established the target operating model and several P0 slices have already landed. This document focuses on what is still missing across the whole program: immature interactions, incomplete evidence, unproven default paths, and remaining release/runtime trust gaps.

## Executive Summary

Clavue is no longer missing the basic building blocks. The repo already has provider profiles, route policy tests, coding regression fixtures, release preflight checks, ledgers, task-board truth fixes, `/init` fixture coverage, companion workflow contracts, stale launcher detection, and parallel-worker recursion guards.

The remaining gap is maturity: Clavue must prove that the complete user path works repeatedly, not only that individual modules pass focused tests. The next upgrade should therefore prioritize evidence-producing workflows and user-facing interaction cleanup over adding more isolated features.

## What Is Already In Place

- Product identity is anchored in `PRODUCT.md` and `ARCHITECTURE.md`.
- Main local gates exist in `package.json`: `npm run check`, `npm run build`, `npm run check:runtime`, provider verification, route-policy tests, and coding-regression smoke.
- World-class ledgers exist under `docs/evals/world-class/`.
- Route-policy coverage exists in `tests/coding-route-policy.test.mjs`, `tests/prompt-route-policy.test.mjs`, provider tests, and `regression-fixtures/`.
- Release preflight exists in `scripts/release-preflight.mjs`.
- Campaign runner exists in `scripts/run-campaign-round.mjs`.
- `/init` coverage now includes Node, Cargo, Python, Go, Makefile, docs-only, nested project, and malformed manifest cases.
- Companion commands now parse workflow verbs instead of falling through to rename behavior.
- Parallel development has recursion guards and full-firepower launch coverage.

## Remaining Missing Areas

### 1. Evidence Is Still Fragmented

The ledgers are valuable but incomplete. Several result rows still have `commit=pending`, the provider-route ledger still records a baseline gap, and no single command produces a full release-quality scorecard.

Impact:

- Quality claims remain hard to audit.
- A release can pass focused tests while still lacking cross-path evidence.
- Reviewers have to manually join data from tests, ledgers, package scripts, and release notes.

Upgrade direction:

- Add one world-class eval command that runs the critical campaigns, provider matrix, coding regression, release preflight, and default-path smoke.
- Emit JSON plus a TSV row that can be appended to `docs/evals/world-class/results.tsv`.
- Require every material release candidate to have a non-pending ledger row.

### 2. The Default User Path Is Not End-To-End Proven

The repo has strong focused coverage, but the complete path is still not a first-class smoke:

1. Install or run packaged CLI.
2. Configure or adopt a provider profile.
3. Run `/init` in a fresh project.
4. Start real development from the generated guidance.
5. Read, edit, test, and recover.
6. Continue after interruption or compaction.
7. Run upgrade/doctor checks.

Impact:

- A new user may still experience friction even when the modules are individually correct.
- "Execution-first" can regress into fragmented setup, validation, or advice-only behavior.

Upgrade direction:

- Create a default-path smoke harness using a temp repo and synthetic provider/profile fixtures where live network is not required.
- Add an online mode that can be run before release when credentials and GitHub/npm access are available.
- Record the result in the onboarding friction ledger.

### 3. Provider Reliability Needs A Deterministic Matrix Ledger

Provider routing is tested, but the evidence is not yet presented as an operator matrix. The missing matrix should include official Anthropic, OpenAI-compatible Responses, Anthropic-compatible proxy, GPT/Codex route, chat-only route, degraded partial-native route, blocked route, missing credentials, and legacy migration.

Impact:

- `/provider doctor` may be correct in code but not auditable row by row.
- Users may still be unsure whether a route is coding-capable, chat-only, degraded, or blocked.
- Route failures can be misdiagnosed as model quality problems.

Upgrade direction:

- Add `scripts/run-provider-matrix.mjs` or extend `verify-provider-route.mjs` to emit stable matrix rows.
- Make every matrix row include status, transport, quality tier, workflow mode, native tool claim, next action, and failure class.
- Append summarized results to `docs/evals/world-class/provider-route-ledger.md`.

### 4. Interaction Surface Is Too Broad And Uneven

The command set is powerful but not consistently mature. There are many commands, feature-flagged commands, hidden internal stubs, compatibility commands, and overlapping setup paths. The current user may not know which surface is canonical.

Observed examples:

- `/provider` is canonical for provider setup, while `/login` still exists as a provider/config path and account auth paths also exist.
- `/team` can inspect readiness, but team creation is still prompt-driven instead of a direct, discoverable command.
- Companion workflows are explicit but inert until the `/mao` bridge exists.
- Hidden/internal stub commands remain in source and registry paths for internal builds.
- `/help` lists many capabilities but does not yet behave like a progressive product map.

Impact:

- Users can choose the wrong entrypoint.
- Advanced surfaces feel bolted on instead of integrated.
- Inert or diagnostic-only commands can be mistaken for execution flows.

Upgrade direction:

- Classify every command as `primary`, `secondary`, `compatibility`, `internal`, or `experimental`.
- Make `/help` and docs reflect that classification.
- Add direct next actions for `/team create`, companion workflow execution, provider repair, and permission recovery.
- Keep compatibility aliases, but make canonical paths visually obvious.

### 5. Permission UX Is Correctness-Heavy But Not Yet Mature

Permission tests exist, but prompt copy and recovery paths still need a product pass. A user should always know why Clavue is asking, what exact scope is requested, what is safe to approve, and how to recover from a denial.

Impact:

- Safe workflows can feel noisy.
- Risky workflows can feel under-explained.
- Recent denials can strand the user without a smallest-safe repair action.

Upgrade direction:

- Add prompt-copy assertions for bash, file edit, PowerShell, MCP, fallback tools, and IDE diff approval.
- Add a recent-denial recovery surface that suggests the smallest scoped rule.
- Add manual UX review gates for the most common permission dialogs.

### 6. Long Sessions Need Realistic Smoke Coverage

There are heap, compaction, memory, and continuity tests. What is still missing is a scripted long-session smoke that resembles real work: many turns, large command output, compaction, route warnings, task-board updates, continuation, and resume.

Impact:

- Long-session reliability is proven by components rather than a complete workflow.
- Regressions in cross-module state transfer can survive focused tests.

Upgrade direction:

- Add a 20-turn temp-repo smoke with read/edit/test, large-output truncation, compaction trigger, continuation prompts, and resume.
- Keep the smoke offline-safe and add an optional online route mode.
- Record the result in `results.tsv`.

### 7. Release Trust Still Depends On Local Discipline

The release preflight is a strong improvement, but trusted publishing evidence is still missing from the current ledgers. GitHub Actions availability, npm latest, tarball extraction, clean `npx`, global launcher checks, and package surface scans should be emitted as one report.

Impact:

- A release can be locally valid but not independently verifiable.
- Manual publish fallback can become the normal path if not explicitly controlled.

Upgrade direction:

- Add a release report generator that collects check/build/package/preflight/provider/coding-regression evidence.
- Make online release evidence appendable to `release-ledger.md`.
- Treat local fallback publishing as emergency-only.

### 8. Build And Source Authority Still Carry Legacy Debt

The architecture says authored source, supported build pipeline, and release artifacts should form one authority chain. The repo still has legacy rebuild paths and auto-stubbing infrastructure that need stricter documentation and allowlist enforcement.

Impact:

- Build failures can be masked by stubs.
- Developers may use the wrong rebuild path.
- Release artifact drift remains harder than necessary to reason about.

Upgrade direction:

- Keep `npm run rebuild:dist` and `npm run check` as the supported paths.
- Move legacy rebuild usage into a clearly documented investigation-only lane.
- Ensure unexpected missing-module stubs fail loudly and are ledgered if intentionally allowed.

### 9. Companion, Team, And Parallel Features Need Execution Contracts

These surfaces now have better intent routing, but they still need stronger end-to-end contracts.

Missing pieces:

- Companion `/girl recap`, `/boy diagnose`, `/boy fix`, and `/bigdaddy review` are contract surfaces, not fully wired execution roles.
- Team creation is not a crisp direct command.
- Parallel execution has launch logic, but needs budget, cancellation, output aggregation, and post-run review UX.

Upgrade direction:

- Wire companion workflows to `/mao` only through a tested bridge.
- Add `/team create` or a guided team-creation flow with provider readiness checks.
- Add parallel budget display, cancellation rules, and final aggregation.

### 10. Product Truth Docs Need Capability Tiers

The README and docs explain many features, but they should explicitly classify capability states:

- Fully supported.
- Supported with degraded behavior.
- Experimental.
- Compatibility-only.
- Internal or hidden.
- Not supported.

Impact:

- Users infer stronger guarantees than the product has proven.
- Support and debugging cost increases.

Upgrade direction:

- Add a capability matrix document.
- Link it from README and provider best-practices docs.
- Add product-truth tests for the most important public claims.

## Version Plan

### v8.9.0 - Evidence And Default-Path Release

Goal: make release quality auditable from one command and one set of ledgers.

Required outcomes:

- World-class eval runner exists.
- Default-path smoke exists.
- Provider matrix ledger has deterministic rows.
- Release report can be generated offline.
- `/init` failure-state rollback and mixed-monorepo gaps are covered.
- Command surface audit has an initial public/internal classification.

### v8.9.1 - Interaction Maturity Release

Goal: reduce confusion on primary user surfaces.

Required outcomes:

- `/help` and docs show canonical paths clearly.
- `/provider` setup has fewer ambiguous branches and clearer repair text.
- `/team` exposes a direct creation or guided creation path.
- Companion workflow commands either execute through `/mao` or explicitly label themselves as planning-only.
- Permission prompts have scoped recovery copy.

### v8.9.2 - Reliability And Cross-Environment Release

Goal: prove the runtime survives realistic work and varied environments.

Required outcomes:

- Long-session smoke exists and passes.
- Cross-node and cross-platform CI matrix is recorded when infrastructure is available.
- Online release preflight evidence is recorded for GitHub Actions, npm, clean `npx`, tarball, and global launcher.
- Parallel execution has budget, cancellation, and aggregation UX.

### v9.0 Candidate - Major Quality Release

Goal: claim major maturity only after evidence is complete.

Required outcomes:

- All P0 and P1 TODOs are closed or explicitly deferred with accepted risk.
- All primary ledgers have non-pending evidence.
- Default-path, provider-route, permission, long-session, release, and product-truth metrics meet target.
- A fresh user can install, configure, initialize, develop, verify, continue, and upgrade without manual rescue.

## Non-Negotiable Rules For This Upgrade

- Do not add new public features unless the default path and evidence gaps improve.
- Do not claim native/coding capability without route matrix evidence.
- Do not advertise an execution workflow if it only returns an inert contract.
- Do not let hidden/internal stubs leak into public product truth.
- Do not ship a release candidate with pending ledger commit IDs.
- Do not rely on local machine state as the only release proof.

## Definition Of Done

The v8.9 maturity pass is complete when:

- `npm run check:runtime` passes.
- The new world-class eval command passes.
- The default-path smoke passes.
- Provider matrix evidence is appended to the ledger.
- Release report is generated and archived.
- Docs classify capability tiers honestly.
- No P0 TODO remains open without an accepted-risk entry.
