feat(R10): implement CI Quality Gates, Contributor Recipes, E2E Smoke Tests, and update docs

START_CONTRIBUTING.md

@@ -1,40 +1,64 @@
 # Start Contributing
 
-## What is this repository?
+Welcome to the **Cowork Local** contributor guide!
 
-Cowork Local is the Cowork Team's product/platform repository: desktop runtime, UI/UX, workspaces, agents, MCP/connectors, security, and reusable platform foundations.
+---
 
-The Cowork Team owns architecture, product behavior, releases, the stable branch, final review, and merge. The FSG AI Core Team is a contributor for selected generic capabilities such as MCP integration, agent capabilities, orchestration/model-routing tests, evaluation/security integration, and reusable platform improvements.
+## 🏛️ Architecture & Ground Rules
 
-## Where are Core AI tasks?
+1. **4-Tier Clean Architecture**:
+   - `domain/`: Business entities and immutable data structures (Pure Python).
+   - `application/`: Application services and orchestration (Pure Python).
+   - `infrastructure/`: External integrations, adapters, persistence, and secrets.
+   - `presentation/`: Desktop UI widgets, PySide6 components, and Qt signals.
+   - **Rule**: `domain/` and `application/` must NEVER import `PySide6` or any UI framework.
 
-Use [fsg-ai-core-assets Issues/Project](http://34.143.229.138/gitea-admin/fsg-ai-core-assets) as the Core AI task source of truth. Pick and assign a contribution task there, then move it to `In Progress`.
+2. **File Size Limit (LOC)**:
+   - Every file in `domain/`, `application/`, `infrastructure/`, and `presentation/` must be `<= 400 LOC`.
 
-Do not copy the Core AI backlog, golden datasets, CASAN assets, agent catalog, or evaluation repository into Cowork Local. Only source/artifacts required by an agreed Cowork runtime contract belong here.
+3. **In-Code Comments**:
+   - All code logic, error handling, and design rationales must be documented with clear **English comments**.
 
-## Make the change
+---
 
-Create a focused branch:
+## 🚀 Development Workflow
 
+### 1. Create a Topic Branch
 ```bash
-git switch -c core-ai/TL-xxx-short-name
+git switch -c feat/my-new-feature
 ```
 
-For Cowork-native work use `feat/`, `fix/`, `test/`, `docs/`, `perf/`, or `refactor/`. Keep one logical change in one Pull Request.
+### 2. Implement Using Contributor Recipes
+Follow the standardized recipes in [`docs/governance/contributor-recipes.md`](docs/governance/contributor-recipes.md):
+- **Recipe 1**: Adding a new AI Model Provider.
+- **Recipe 2**: Adding a new Tool or MCP Server.
+- **Recipe 3**: Adding a new UI Screen or Widget.
 
-Run the application from the parent directory with `python -m cowork_local`. Run the current automated test suite from this repository with:
+### 3. Run CASAN Quality Gate Locally
+Before committing and pushing your branch, ensure all quality gates pass:
 
 ```bash
-python -m pip install -r requirements-test.txt
-python -m pytest tests -q
+python scripts/run_quality_gate.py
 ```
 
-Use environment variables for credentials; never commit `.env`, `~/.cowork_local/`, logs, customer data, or generated runtime files.
+---
 
-## Review and completion
+## 🧪 Testing Pyramid
 
-Before opening a Pull Request, obtain Core AI pre-review and move the Core task to `Review`. Open the Pull Request in Cowork Local with the Core repository URL, issue, task ID, scope, validation evidence, and security impact. Then move the Core task to `Upstream Review`.
+We maintain a strict multi-tier test pyramid:
+- `tests/unit/`: Fast unit tests (no I/O, < 0.05s).
+- `tests/contracts/`: Contract tests for Provider and Tool interfaces.
+- `tests/integration/`: Component integration tests (Qt offscreen).
+- `tests/e2e/`: End-to-End release smoke tests (`pytest tests/e2e/test_smoke.py`).
+- `tests/fakes/`: Reusable in-memory test doubles (`FakeProvider`, `FakeToolRuntime`).
 
-The Cowork Team may request changes or approve and merge. A Core AI task is `Done` only after the Cowork Pull Request is merged—not when implementation or Core AI review finishes. Record the Pull Request and merge reference in the Core issue.
+---
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for conventions and `docs/governance/` for ownership, review, and Definition of Done.
+## 📋 Definition of Done (DoD)
+
+A Pull Request is ready for merge only when:
+- [x] All production files are `<= 400 LOC` (`python scripts/check_loc.py`).
+- [x] Clean Architecture boundary check has 0 violations (`python scripts/check_imports.py`).
+- [x] Secrets audit finds 0 plaintext credentials (`python scripts/audit_security.py`).
+- [x] 100% of test suite passes without regressions (`pytest tests/`).
+- [x] E2E release smoke tests pass (`pytest tests/e2e/test_smoke.py`).