# World-Class Autoresearch Hardening Plan - 2026-04-25

## Reference Model

This plan adapts the operating model from `karpathy/autoresearch` to Clavue.

Transferable rules:

- Use Markdown as the control plane for autonomous work.
- Keep scope narrow enough that each cycle has a measurable result.
- Establish a baseline before changing behavior.
- Use one primary metric per cycle.
- Keep an append-only results ledger.
- Keep improvements only when evidence beats the baseline.
- Prefer simpler code when the measured outcome is equal.

For Clavue, `PRODUCT.md`, `ARCHITECTURE.md`, and `/retro` are the equivalent of `program.md`. The metric is not validation loss. It is default-path product quality: setup -> code -> validate -> recover -> deliver.

## Round 1 Plan - Reality Scan

Goal: decide whether current settings and product behavior are already best practice.

Baseline evidence:

- `PRODUCT.md` defines Clavue as an execution-first AI coding CLI, not a provider shell.
- `ARCHITECTURE.md` defines two authority chains: authored source -> release artifact, and provider/model capabilities -> runtime workflow behavior.
- `docs/clavue-provider-model-best-practices.md` already documents provider/model source of truth, `.clavue` ownership, and safe custom API setup.
- `v8.8.82` adds early Node heap bootstrap, solving the previous ~4GB local OOM failure class.
- `/retro` exists, but it does not force a minimum of three completed patrol cycles before success.

Scorecard:

- Product truth: strong. Clavue identity is explicit and provider routing is correctly framed as a capability.
- Compatibility: strong but still needs continuous route and release gates.
- Stability: improved by heap bootstrap, proactive compaction, and release verification.
- Interaction logic: strong in setup/provider flows, weaker in autonomous retrospective discipline.
- Reliability: good gates exist, but the autonomous loop should make keep/discard decisions harder to fake.

Decision: keep the current provider/model and `.clavue` direction. Upgrade the retrospective operating loop.

## Round 2 Plan - Critique And Ranking

Candidate 1: Make `/retro` enforce at least three documented patrol cycles.

- User impact: 5
- Roadmap alignment: 5
- Implementation risk: 5
- Verification clarity: 5
- Simplicity payoff: 5
- total = 25/25

Candidate 2: Add a `campaign:world-class` gate for product truth, retro discipline, heap resilience, provider runtime, and release packaging.

- User impact: 4
- Roadmap alignment: 5
- Implementation risk: 5
- Verification clarity: 5
- Simplicity payoff: 4
- total = 23/25

Candidate 3: Add a provider drift doctor that compares current `/provider` state against documented best practice.

- User impact: 4
- Roadmap alignment: 5
- Implementation risk: 3
- Verification clarity: 4
- Simplicity payoff: 3
- total = 19/25

Candidate 4: Add deeper live memory leak instrumentation beyond the heap bootstrap.

- User impact: 4
- Roadmap alignment: 4
- Implementation risk: 2
- Verification clarity: 3
- Simplicity payoff: 2
- total = 15/25

Chosen slice: combine candidates 1 and 2 as one coherent "world-class patrol loop" upgrade. It directly matches the user request, improves default operating discipline, and is easy to verify.

## Round 3 Plan - Upgrade And Evaluation

Implementation goals:

- `/retro` must explicitly require at least three complete patrol cycles before final success.
- Every patrol must have a plan artifact, baseline, target metric, implementation notes, verification, scorecard, and keep/discard decision.
- The rolling ledger must record each completed patrol.
- The repo must expose a `campaign:world-class` command that runs the highest-signal quality gates for this product path.

Verification plan:

- `node --test tests/retro-command.test.mjs`
- `node --test tests/campaign-round.test.mjs`
- `node scripts/run-campaign-round.mjs --campaign world-class-core --out /tmp/clavue-world-class-campaign.json`
- `npm run rebuild:dist`
- `node scripts/verify-dist.mjs`

Keep criteria:

- `/retro` prompt contains the minimum three-patrol contract.
- The prompt requires per-round plan docs and a keep/discard ledger.
- The world-class campaign is present and script-accessible.
- Dist verification still passes after rebuild.

World-class impact:

- Compatibility: improves by making provider/runtime/release gates part of a named campaign.
- Stability: improves by requiring baselines and fixed verification before keeping changes.
- Interaction logic: improves by turning "review this" into a concrete three-cycle operating loop.
- Reliability: improves by making evidence and keep/discard logging mandatory.
