CodeVetter docs

The local-first knowledge system for the CodeVetter repository.

This is the canonical knowledge system for the CodeVetter repository. The committed Markdown here is the source of truth; Blume is only the presentation and search layer.

• Short current view: STATUS.md
• Deep timeline + feature log: PROJECT_STATUS.md
• Agent bootloader: agents.md
• Product readme: README.md

Product

• overview.md — what CodeVetter is, durable scope, capability matrix, strategy.
• capabilities.md — UI, CLI, MCP, underlying-tool, and future-capability glossary.
• surfaces.md — nav tabs, URL-only routes, removed surfaces.
• synthetic-user-qa.md — runtime proof layer for agent-written code.
• trex-change-preview.md — exact PR or commit-range verification against an existing preview.

Architecture

• Start here: how-it-works.md — end-to-end pedagogical overview of the whole system (components, review flow, key decisions).
• overview.md — layers, critical invariants, what was removed.
• ipc-and-commands.md — the IPC bridge and command map.
• data-model.md — SQLite tables and persistence boundaries.
• review-pipeline.md — review → fix → re-review → proof.
• graph-and-history.md — canonical structural graph + release history workbench.
• repo-unpacked.md — evidence-backed repo briefs.
• mcp-sidecar.md — opt-in local MCP server.
• trex-mcp-projection.md — future agent-triggered verification boundary without weakening the read-only MCP.
• history-evidence-import.md — importing provider-side outcomes.
• verification-workbench.md — additive evidence identities, retention, managed-run, intent, and performance records.
• native-migration-matrix.md — no-regression map and release gates for the sole native macOS app.
• native-rust-boundary.md — measured hybrid ownership split between in-process reads and supervised execution.

Decisions

• mcp-sdk.md — chose rmcp 2.2.0 for the MCP sidecar.
• oss-integration.md — OSS integration evaluation.
• structural-graph-contract.md — first-party code-graph capability and release contract.

Development

• setup.md — prerequisites, install, run.
• testing.md — native, Rust, CLI/MCP, package, and code-health gates.
• performance.md — native, Rust, MCP, and exact-package performance gates.
• native-macos.md — native Evidence Workbench toolchain, ownership, and qualification boundaries.
• benchmark.md — catch-rate benchmark.
• agent-task-corpus.md — immutable coding-agent task packages and fail-closed readiness.
• verification-receipts.md — ingest project-runner evidence, compare regressions, and explain test blast radius.
• configuration.md — native identity, settings, data, and updater configuration.
• docs.md — how to write, validate, and render docs.

Operations

• automation-contract.md — privacy-safe product, release, reliability, and Foundry evidence contracts.
• release-pipeline.md — desktop release chain.
• signing-and-updates.md — Developer ID signing, notarization, and Sparkle auto-update inputs.
• landing-deploy.md — Cloudflare Pages deploy.
• ci.md — CI workflow and order.

Jobs

• weekly-quality.md — Monday cron canary.

Runbooks

• cut-a-release.md — ship a new desktop version.
• deploy-landing.md — deploy the Astro site.

Knowledge

• failed-approaches.md — things that broke and the constraints they left.
• competitive-landscape.md — AI code review competitive landscape.
• performance-lab-publication.md — published optimization experiments, external PRs, and evidence boundaries.
• tooling-decisions.md — what CodeVetter embeds instead of building, what it refuses, and why. Hub for the five evaluations below.
• tooling-secrets-and-supply-chain.md — secret scanners and dependency/vulnerability scanners.
• tooling-coverage.md — coverage collection across Rust/TS/Python, the LCOV transport decision, diff-coverage traps.
• tooling-agent-benchmarks.md — public agent benchmark corpora, graded on determinism and licensing.
• tooling-documentation.md — the DeepWiki reject and what would fit instead.
• tooling-sandboxing.md — isolation for running untrusted agent code, determinism controls, SARIF analyzers.
• codebase-context-tools-landscape.md — April 2026 survey of codebase indexing and context tooling.

Learnings

• README.md — learning roadmap and coverage map.
• new-things.md — platform + stack concepts.
• telemetry-and-indexing.md — the usage pipeline.
• verification-and-judgment.md — the verification stack.

Archive

Superseded docs kept for git history. Do not treat as current. These are excluded from the rendered Blume site (see blume.config.ts), so the links below point at the files in the repo on GitHub.

• DECISIONS.md — older decision log.
• LESSONS.md — older lessons.
• PRD-*.md — scoped PRDs for shipped slices.
• stale-competitive-landscape-2026-03.md — full March competitor survey + April OSS GTM plan.
• stale-architecture-2026-04.md — pre-desloppification architecture (removed packages//workers/).
• stale-development-2026-04.md
• stale-configuration-2026-04.md
• stale-testing-2026-04.md
• stale-performance-harness-2026-09.md — retired React/Tauri performance harness and historical measurements.
• stale-native-agent-island-2026-09.md — retired helper prototype; any future status island is a side quest.
• stale-repo-unpacked-2026-09.md — retired React/Tauri implementation notes.
• planning-codebase/ — pre-desloppification .planning/codebase/ docs.

Open questions

Tracked in STATUS.md under “Unresolved questions”. Do not invent answers in docs; mark gaps explicitly.