Merge quality gate baseline work

Bring the detached quality-gate worktree into local main while preserving the existing main-only desktop diagnostics commits. This merge lands the PR/release quality gate, live model baselines, provider selector docs, AGENTS automation rules, and repository hygiene for generated artifacts.

Constraint: Local main had commits not present in the detached worktree, so fast-forward merge was not possible.

Rejected: Rebase the detached worktree | rewriting the already-verified local commits would discard the exact release-gate evidence SHA chain.

Confidence: high

Scope-risk: broad

Directive: Keep quality reports and local Superpowers plans out of future commits; use report summaries as evidence, not tracked artifacts.

Tested: bun run quality:gate --mode release --allow-live --provider-model codingplan:main:codingplan-main --provider-model minimax:main:minimax-main

Not-tested: post-merge full rerun on main; merge had no content conflicts.

Author: NanmiCoder

.gitignore

@@ -22,6 +22,9 @@ extracted-natives/
 # E2E screenshots
 e2e-*.png
 
+# Quality gate reports
+artifacts/quality-runs/
+
 # Desktop build output
 desktop/dist/
 desktop/build-artifacts/

AGENTS.md

@@ -13,6 +13,10 @@ Install root dependencies with `bun install`, then install desktop dependencies
 - `cd desktop && bun run build`: type-check and produce a production web build.
 - `cd desktop && bun run test`: run Vitest suites.
 - `cd desktop && bun run lint`: run TypeScript no-emit checks.
+- `bun run quality:providers`: list configured provider/model selectors for live agent baselines.
+- `bun run quality:pr`: run the local PR quality gate and write a report under `artifacts/quality-runs/`.
+- `bun run quality:gate --mode baseline --allow-live --provider-model <provider:model[:label]>`: run live Coding Agent baseline cases, including desktop agent-browser smoke.
+- `bun run quality:gate --mode release --allow-live --provider-model <provider:model[:label]>`: run the release gate with live baseline coverage.
 
 ## Desktop Release Workflow
 - Desktop releases are built remotely by GitHub Actions, not by uploading local build artifacts.
@@ -32,6 +36,23 @@ Use TypeScript with 2-space indentation, ESM imports, and no semicolons to match
 ## Testing Guidelines
 Desktop tests use Vitest with Testing Library in a `jsdom` environment. Name tests `*.test.ts` or `*.test.tsx`; colocate focused tests near the file or place broader coverage in `desktop/src/__tests__/`. No coverage gate is configured, so add regression tests for any behavior you change and run the relevant suites before opening a PR.
 
+## Quality Gate Automation
+Future Coding Agents should run the right local gate themselves before claiming a change is ready. Do not ask the user to manually run the commands unless credentials, local model access, or machine resources are missing.
+
+- For normal code changes, run the narrow relevant check first, then `bun run quality:pr` before a PR-ready or merge-ready claim.
+- Use `bun run check:server` for `src/server`, `src/tools`, provider/runtime, MCP, OAuth, WebSocket, or API behavior changes.
+- Use `bun run check:desktop` for `desktop/src` UI, stores, API clients, and desktop web behavior changes.
+- Use `bun run check:native` for `desktop/src-tauri`, sidecars, native packaging, release, or platform startup behavior changes.
+- Use `bun run check:adapters` for `adapters/`; on a fresh checkout run `cd adapters && bun install` first if dependencies are missing.
+- Use `bun run check:docs` for docs, VitePress, README, or docs workflow changes.
+- For chat, agent loop, tool execution, provider routing, desktop chat UI, CLI task execution, or other core Coding Agent paths, also run a live baseline when local providers are available: first `bun run quality:providers`, then choose one or more copyable selectors and run `bun run quality:gate --mode baseline --allow-live --provider-model <provider:model[:label]>`.
+- For release readiness, run `bun run quality:gate --mode release --allow-live --provider-model <provider:model[:label]>` with at least one real provider/model selector. Prefer multiple providers when quota is available.
+- If no live provider is configured, or a provider quota/key is unavailable, run the non-live gate anyway and report the live-baseline blocker explicitly instead of claiming full release confidence.
+- `bun run check:docs` executes `npm ci`, which can rebuild root `node_modules`. Run docs checks sequentially, not in parallel with `quality:pr`, `check:native`, or other commands that depend on the same installed packages.
+- Quality reports are written to `artifacts/quality-runs/<timestamp>/`. Summarize the final report path and the pass/fail counts in handoffs and PR descriptions.
+- Do not commit generated `artifacts/quality-runs/`, local `.omx/` state, `node_modules/`, `desktop/node_modules/`, or adapter dependency folders.
+- Do not claim "complete", "ready to merge", or "ready to release" without either running the matching gate or naming the exact blocker that prevented it.
+
 ## Commit & Pull Request Guidelines
 Recent history follows Conventional Commit prefixes such as `feat:`, `fix:`, and `docs:`. Keep subjects imperative and scoped to one change. PRs should explain the user-visible impact, list verification steps, link related issues, and include screenshots for desktop or docs UI changes. Keep diffs reviewable and call out any follow-up work or known gaps.
 Branch names should use normal product prefixes such as `fix/xxx`, `feat/xxx`, or `docs/xxx`; do not create `codex/`-prefixed branches in this repository.

CONTRIBUTING.md

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for helping improve Claude Code Haha.
+
+For the full contributor guide, including local checks, live model baselines, quality-gate reports, and PR expectations, see:
+
+- Chinese: [docs/guide/contributing.md](docs/guide/contributing.md)
+- English: [docs/en/guide/contributing.md](docs/en/guide/contributing.md)
+
+Most contributors should run this before opening a PR:
+
+```bash
+bun install
+bun run quality:pr
+```
+
+If you run adapter or native checks on a fresh clone, install adapter dependencies too:
+
+```bash
+cd adapters
+bun install
+```
+
+If your change touches the desktop chat path, provider/runtime selection, CLI bridge, permissions, tools, file editing, or release packaging, also run a live baseline with your own local model provider:
+
+```bash
+bun run quality:providers
+bun run quality:gate --mode baseline --allow-live --provider-model <selector>:main
+```
+
+Quality reports are written under `artifacts/quality-runs/<timestamp>/`.

README.en.md

@@ -195,6 +195,7 @@ http://127.0.0.1:2024
 |------|------|
 | [Environment Variables](docs/en/guide/env-vars.md) | Full env var reference and configuration methods |
 | [Third-Party Models](docs/en/guide/third-party-models.md) | Using OpenAI / DeepSeek / Ollama and other non-Anthropic models |
+| [Contributing](docs/en/guide/contributing.md) | Local tests, live model baselines, PR gates, and release gates |
 | [Memory System](docs/memory/01-usage-guide.md) | Cross-session persistent memory usage and implementation |
 | [Multi-Agent System](docs/agent/01-usage-guide.md) | Agent orchestration, parallel tasks and Teams collaboration |
 | [Skills System](docs/skills/01-usage-guide.md) | Extensible capability plugins, custom workflows and conditional activation |

README.md

@@ -195,6 +195,7 @@ http://127.0.0.1:2024
 |------|------|
 | [环境变量](docs/guide/env-vars.md) | 完整环境变量参考和配置方式 |
 | [第三方模型](docs/guide/third-party-models.md) | 接入 OpenAI / DeepSeek / Ollama 等非 Anthropic 模型 |
+| [贡献与质量门禁](docs/guide/contributing.md) | 本地测试、真实模型 baseline、PR 和 release 门禁 |
 | [记忆系统](docs/memory/01-usage-guide.md) | 跨会话持久化记忆的使用与实现 |
 | [多 Agent 系统](docs/agent/01-usage-guide.md) | 多代理编排、并行任务执行与 Teams 协作 |
 | [Skills 系统](docs/skills/01-usage-guide.md) | 可扩展能力插件、自定义工作流与条件激活 |

docs/.vitepress/config.mts

@@ -24,6 +24,7 @@ const zhSidebar = [
       { text: '第三方模型', link: '/guide/third-party-models' },
       { text: '全局使用', link: '/guide/global-usage' },
       { text: '常见问题', link: '/guide/faq' },
+      { text: '贡献与质量门禁', link: '/guide/contributing' },
     ],
   },
   {
@@ -109,6 +110,7 @@ const enSidebar = [
       { text: 'Third-Party Models', link: '/en/guide/third-party-models' },
       { text: 'Global Usage', link: '/en/guide/global-usage' },
       { text: 'FAQ', link: '/en/guide/faq' },
+      { text: 'Contributing', link: '/en/guide/contributing' },
     ],
   },
   {

docs/en/guide/contributing.md

@@ -0,0 +1,164 @@
+# Contributing and Local Quality Gates
+
+This guide explains how to install, develop, test, and run the local quality gates before opening a PR. The goal is to help maintainers and contributors answer one question before review: did this change break the core Coding Agent workflow?
+
+## Setup
+
+Install root dependencies with Bun:
+
+```bash
+bun install
+```
+
+If your change touches `desktop/`, also install desktop dependencies:
+
+```bash
+cd desktop
+bun install
+```
+
+If your change touches `adapters/`, or if you run `check:adapters` / `check:native`, install adapter dependencies:
+
+```bash
+cd adapters
+bun install
+```
+
+Do not commit local artifacts such as `artifacts/quality-runs/`, `node_modules/`, or `desktop/node_modules/`.
+
+## Required PR Gate
+
+Before opening a normal PR, run:
+
+```bash
+bun run quality:pr
+```
+
+This gate does not call real models, so every contributor can run it locally. It writes reports to:
+
+```text
+artifacts/quality-runs/<timestamp>/report.md
+artifacts/quality-runs/<timestamp>/report.json
+```
+
+Include the commands you ran and the report summary in your PR description.
+
+## Area-Specific Checks
+
+Run the checks that match the files you changed:
+
+```bash
+bun run check:server      # Server API, WebSocket, providers, sessions, and related tests
+bun run check:desktop     # Desktop lint, Vitest, and production build
+bun run check:adapters    # IM adapter tests
+bun run check:native      # Desktop sidecars and Tauri native checks
+bun run check:docs        # Docs build, using npm ci + docs:build
+```
+
+Focused tests are fine while developing, but run `bun run quality:pr` before sending the PR.
+
+## Live Model Baseline
+
+`quality:baseline` runs real Coding Agent tasks: it starts the local server, creates isolated fixtures, asks a model through chat to fix code, runs tests, and saves transcripts, diffs, verification logs, and a report.
+
+The default baseline command does not call real models:
+
+```bash
+bun run quality:baseline
+```
+
+To actually call models, pass `--allow-live` and choose a local provider.
+
+First list your local providers and copyable selectors:
+
+```bash
+bun run quality:providers
+```
+
+Example output:
+
+```text
+Saved providers:
+  MiniMax
+    selector: minimax
+    main: MiniMax-M2.7-highspeed
+      --provider-model minimax:main:minimax-main
+```
+
+Copy one of the listed values:
+
+```bash
+bun run quality:gate --mode baseline --allow-live --provider-model minimax:main:minimax-main
+```
+
+You can run multiple models in one pass:
+
+```bash
+bun run quality:gate --mode baseline --allow-live \
+  --provider-model codingplan:main:codingplan-main \
+  --provider-model minimax:main:minimax-main
+```
+
+Provider selectors come from the providers saved in your local Desktop Settings > Providers page. Contributors do not need the maintainer's provider UUIDs or vendor accounts. They can add their own provider locally, run `bun run quality:providers`, and choose their own model.
+
+## When To Run The Baseline
+
+Run the live baseline for changes touching:
+
+- Desktop chat, session resume, WebSocket, or the CLI bridge
+- Provider, model, or runtime selection
+- Permissions, tool calls, file edits, and task execution
+- agent-browser smoke, Computer Use, Skills, or MCP
+- Release preparation or broad cross-module refactors
+
+If you do not have model access, still run `bun run quality:pr` and state in the PR why the live baseline was not run.
+
+## Release Gate
+
+Before a release, run release mode:
+
+```bash
+bun run quality:gate --mode release --allow-live --provider-model <selector>:main
+```
+
+Release mode composes PR checks, baseline catalog validation, live baseline cases, desktop smoke, and native checks. Reports are written to `artifacts/quality-runs/<timestamp>/`.
+
+## PR Workflow
+
+1. Create a product branch such as `fix/session-reconnect` or `feat/provider-quality-gate`.
+2. Install dependencies and make the change.
+3. Add tests for behavior changes.
+4. Run focused checks for the affected area.
+5. Run `bun run quality:pr`.
+6. Run the live baseline for high-risk changes.
+7. In the PR description, include user impact, verification commands, report summary, and known risks.
+
+## FAQ
+
+### Can I run checks without a provider?
+
+Yes. Run the normal PR gate:
+
+```bash
+bun run quality:pr
+```
+
+Only the live baseline needs a real model. Add your provider in Desktop Settings > Providers, then run:
+
+```bash
+bun run quality:providers
+```
+
+### What if provider selectors conflict?
+
+If two provider names produce the same selector, `quality:providers` falls back to the provider ID. Copy the `--provider-model ...` value it prints.
+
+### What if a model ID contains a colon?
+
+Prefer role selectors:
+
+```bash
+--provider-model custom:haiku:custom-haiku
+```
+
+The runner resolves `haiku` to the real model ID from your local provider configuration.