# Clavue v8.9 TODO List

Date: 2026-04-30

This TODO list implements `docs/clavue-v8.9-upgrade-plan-2026-04-30.md`. It is ordered by release risk, not by implementation convenience.

## P0 - Must Finish Before v8.9.0

- [x] `V89-P0-01` Add a world-class eval runner.
  - Objective: create one command that runs campaign core checks, provider smoke, route-policy tests, coding-regression smoke, release preflight offline, and default-path smoke.
  - Suggested files: `scripts/run-world-class-evals.mjs`, `package.json`, `docs/evals/world-class/results.tsv`.
  - Gates: `npm run campaign:world-class`, `npm run verify:provider:smoke`, `npm run test:route-policy`, `npm run test:coding-regression`, `node scripts/release-preflight.mjs --offline --skip-local-launcher`.
  - Evidence: JSON report plus one non-pending TSV row.
  - Verified: `node --test tests/world-class-evals.test.mjs`; `npm run eval:world-class -- --out docs/evals/world-class/world-class-eval-report.json --append-tsv docs/evals/world-class/results.tsv --round local-v89-p0-01-resume` passed 6/6 gates and appended a non-pending TSV row.

- [x] `V89-P0-02` Add a default-path smoke harness.
  - Objective: prove install/run, provider setup or profile adoption, `/init`, read/edit/test, continuation, doctor, and upgrade diagnostics as one workflow.
  - Suggested files: `scripts/run-default-path-smoke.mjs`, `tests/default-path-smoke.test.mjs`, `docs/evals/world-class/onboarding-friction-ledger.md`.
  - Gates: offline smoke from a temp repo; optional online mode before release.
  - Evidence: onboarding friction ledger entry with commands and result.
  - Verified: `node --test tests/default-path-smoke.test.mjs`; `npm run smoke:default-path -- --out docs/evals/world-class/default-path-smoke-report.json --append-ledger docs/evals/world-class/onboarding-friction-ledger.md`.

- [x] `V89-P0-03` Build the provider route matrix ledger.
  - Objective: produce deterministic rows for official, OpenAI-compatible, Anthropic-compatible proxy, GPT/Codex, chat-only, degraded, blocked, missing credential, and legacy migration states.
  - Suggested files: `scripts/run-provider-matrix.mjs` or `scripts/verify-provider-route.mjs`, `tests/provider-cli.test.mjs`, `tests/provider-runtime-core.test.mjs`, `docs/evals/world-class/provider-route-ledger.md`.
  - Gates: `npm run verify:provider:smoke`, `npm run test:route-policy`, focused provider tests.
  - Evidence: matrix rows include route, transport, quality tier, workflow mode, native-tool claim, next action, and failure class.
  - Verified: `node --test tests/provider-matrix.test.mjs`; `npm run provider:matrix -- --out /tmp/clavue-provider-matrix-resume.json --append-ledger /tmp/clavue-provider-route-ledger-resume.md`.

- [x] `V89-P0-04` Finish `/init` failure-state coverage.
  - Objective: prove failed writes do not mark onboarding complete and mixed monorepos produce explicit guidance instead of vague summaries.
  - Suggested files: `src/commands/init.ts`, `tests/init-command.test.mjs`, `src/projectOnboardingState.ts`.
  - Gates: `node --test tests/init-command.test.mjs`.
  - Evidence: onboarding friction ledger entry for unwritable target and mixed monorepo behavior.
  - Verified: `node --test tests/init-command.test.mjs` passed 12/12 after `npm run rebuild:dist`.

- [x] `V89-P0-05` Add a release quality report.
  - Objective: summarize build, dist verification, package preview, release preflight, provider smoke, coding regression, fresh `npx`, tarball, npm, and GitHub Actions evidence.
  - Suggested files: `scripts/generate-release-report.mjs`, `scripts/release-preflight.mjs`, `tests/release-pipeline.test.mjs`, `docs/evals/world-class/release-ledger.md`.
  - Gates: `npm run check`, `npm run build`, `npm run package:release` when artifacts matter, online preflight when release credentials are available.
  - Evidence: `docs/evals/world-class/release-quality-report.json` plus release-ledger entry.
  - Verified: `node --test tests/release-pipeline.test.mjs`; `npm run release:report`.

- [x] `V89-P0-06` Audit and classify command surfaces.
  - Objective: classify commands as primary, secondary, compatibility, internal, experimental, or hidden; make `/help` and docs reflect canonical flows.
  - Suggested files: `src/commands.ts`, `src/components/HelpV2/*`, `tests/slash-command-surfaces.test.mjs`, `tests/product-truth-surfaces.test.mjs`, `README.md`.
  - Gates: command surface tests and product-truth tests.
  - Evidence: `src/commands.ts` now contains the command classification table; `/help` filters public built-ins through declared classifications; README documents canonical primary and secondary surfaces without public internal stubs.
  - Verified: `node --test tests/slash-command-surfaces.test.mjs`; `npm run rebuild:dist`; `node --test tests/slash-command-surfaces.test.mjs tests/product-truth-surfaces.test.mjs`; `node scripts/verify-dist.mjs`.

- [ ] `V89-P0-07` Clear pending ledger IDs before release candidate.
  - Objective: replace `commit=pending` rows with actual commit IDs or accepted-risk notes.
  - Suggested files: `docs/evals/world-class/results.tsv`, `docs/evals/world-class/keep-discard-ledger.md`.
  - Gates: script or manual validation that no release-candidate row has `pending`.
  - Evidence: clean ledger before tag.

## P1 - Target For v8.9.1

- [ ] `V89-P1-01` Reduce provider setup friction.
  - Objective: make the fastest path obvious, reduce branch count, clarify model-slot inheritance, and improve invalid URL/key recovery.
  - Suggested files: `src/components/ProviderSetupWizard.tsx`, `src/components/providerSetupWizardHelpers.ts`, provider setup tests.
  - Gates: provider setup wizard tests and manual first-run copy review.

- [ ] `V89-P1-02` Mature permission prompt recovery.
  - Objective: every common permission prompt explains why it appears, exact scope, risk, and smallest safe recovery after denial.
  - Suggested files: `src/components/permissions/*`, `src/hooks/toolPermission/*`, `tests/permission-authorization-flow.test.mjs`.
  - Gates: focused permission tests plus manual prompt-copy review.

- [ ] `V89-P1-03` Add direct team creation or guided creation.
  - Objective: `/team` should offer an explicit creation path when no teams exist instead of relying on a free-form prompt.
  - Suggested files: `src/commands/team/team.tsx`, `src/utils/teamDiscovery.js`, team tests.
  - Gates: `node --test tests/team-command.test.mjs`.

- [ ] `V89-P1-04` Wire companion workflows to `/mao` through a tested bridge.
  - Objective: `/boy fix` and `/bigdaddy review` should either execute through `/mao` or clearly label the command as planning-only.
  - Suggested files: `src/buddy/maoBridge.ts`, `src/commands/companion/shared.tsx`, `tests/companion-actions.test.mjs`, new bridge tests.
  - Gates: companion action tests, Mao runtime tests, no-recursion tests.

- [ ] `V89-P1-05` Add parallel execution budget and aggregation UX.
  - Objective: show worker count, budget, cancellation behavior, partial failure handling, and final merged result.
  - Suggested files: `src/commands/parallel/*`, `tests/parallel-development.test.mjs`, task-board rendering tests.
  - Gates: parallel tests and manual output review.

- [ ] `V89-P1-06` Publish a capability tier document.
  - Objective: classify fully supported, degraded, experimental, compatibility-only, internal, and unsupported features.
  - Suggested files: `docs/clavue-capability-tiers.md`, `README.md`, `tests/product-truth-surfaces.test.mjs`.
  - Gates: product-truth tests.

## P2 - Target For v8.9.2 Or Later

- [ ] `V89-P2-01` Add realistic long-session smoke.
  - Objective: run a 20-turn temp-repo scenario with read/edit/test, large output, compaction, continuation, resume, and task-board state.
  - Suggested files: `scripts/run-long-session-smoke.mjs`, long-session tests, world-class results ledger.
  - Gates: offline smoke; optional online route mode.

- [ ] `V89-P2-02` Expand cross-environment compatibility evidence.
  - Objective: record Node 18/20/24, macOS, Linux, shell, non-interactive, tarball, global install, and clean `npx` checks.
  - Suggested files: CI workflow, release report generator, release ledger.
  - Gates: CI matrix or documented local equivalents.

- [ ] `V89-P2-03` Tighten build auto-stub authority.
  - Objective: ensure unexpected missing modules fail loudly and legacy rebuild paths remain investigation-only.
  - Suggested files: `scripts/build-plugin.mjs`, `scripts/verify-dist.mjs`, build tests.
  - Gates: source purity, dist verification, build tests.

- [ ] `V89-P2-04` Complete plugin and settings TODOs that affect visible maturity.
  - Objective: scan local plugin directories in marketplace UI and replace placeholder Settings/MCP sections with real diagnostics.
  - Suggested files: `src/commands/plugin/BrowseMarketplace.tsx`, `src/components/Settings/Settings.tsx`, `src/components/Settings/Config.tsx`.
  - Gates: plugin/settings tests or manual TUI review.

- [ ] `V89-P2-05` Improve IDE diff lifecycle handling.
  - Objective: add timeout, auto-approval status update, and cleanup behavior for IDE diff approval.
  - Suggested files: `src/hooks/useDiffInIDE.ts`, permission tests.
  - Gates: focused hook tests or manual IDE smoke.

- [ ] `V89-P2-06` Harden MCP auth and diagnostics.
  - Objective: add cross-process refresh locking, avoid JWT argv exposure, and expand MCP parsing diagnostics.
  - Suggested files: `src/services/mcp/auth.ts`, `src/commands/mcp/xaaIdpCommand.ts`, `src/components/mcp/McpParsingWarnings.tsx`.
  - Gates: MCP auth tests and security review.

## Recommended PR Sequence

1. `V89-P0-01` world-class eval runner.
2. `V89-P0-03` provider route matrix ledger.
3. `V89-P0-02` default-path smoke.
4. `V89-P0-04` `/init` failure-state coverage.
5. `V89-P0-06` command surface classification.
6. `V89-P0-05` release quality report.
7. `V89-P0-07` ledger cleanup before release candidate.

## Release Candidate Gate

Do not cut a v8.9 release candidate until:

- [ ] All P0 items are closed or have explicit accepted-risk ledger entries.
- [ ] `npm run check` passes.
- [ ] `npm run build` passes.
- [ ] `npm run check:runtime` passes.
- [ ] The new world-class eval runner passes.
- [ ] The default-path smoke passes.
- [ ] Provider matrix evidence is recorded.
- [ ] Release quality report is generated.
- [ ] No release-candidate ledger row contains `commit=pending`.
