docs(contrib): clarify CI lanes and parity gates

CONTRIBUTING.md

@@ -76,6 +76,22 @@ Rules:
 - Treat `hotfix/*` as maintainer-only emergency flow from `main`.
 - Delete your branch after merge.
 
+## CI and Release Flow
+
+CCS now uses three separate automation lanes:
+
+- `CI` runs on pull requests to `dev` and `main`. This is the review gate for contributor branches.
+- `Push CI` runs after a merge lands on `dev`. This is the code-quality signal for the shared `dev` branch.
+- `Dev Release` publishes the `@dev` package after `dev` changes land. It is release automation, not the primary contributor quality signal.
+
+If `Dev Release` is red but your PR checks were green, check `Push CI` before assuming the merged code is broken.
+
+If `CI` or `Push CI` stays queued for more than 10 minutes, the self-hosted runner is probably offline. That is a maintainer issue, not a contributor mistake.
+
+## AI Agent Rules
+
+`CONTRIBUTING.md` is the human entry point. For AI agents working in this repo, the authoritative automation and workflow rules live in [CLAUDE.md](./CLAUDE.md).
+
 ## AI Review Lane
 
 CCS PR review no longer depends on `anthropics/claude-code-action`. The repository review lane is self-hosted PR-Agent:
@@ -129,16 +145,35 @@ Use `bun run dev` from the repo root when working on the local dashboard experie
 
 ## Validation
 
-If you can, run these before you open or update a PR:
+Run this fast local gate before you open or update a PR:
 
 ```bash
 bun run format
 bun run lint:fix
 bun run validate
+```
+
+`bun run validate` is the day-to-day contributor gate. It runs:
+
+- `typecheck`
+- `lint`
+- `format:check`
+- `test:fast`
+
+Before you ask for review, or whenever you want the closest local equivalent to PR CI, run:
+
+```bash
 bun run validate:ci-parity
 ```
 
-If you changed the dashboard:
+`bun run validate:ci-parity` adds:
+
+- branch freshness check against `origin/dev` or `origin/main`
+- `build:all`
+- full non-e2e test suite via `test:all`
+- `test:e2e` with `CCS_E2E_SKIP_BUILD=1`
+
+If you changed the dashboard, run the UI gate too:
 
 ```bash
 cd ui
@@ -155,7 +190,17 @@ bun run test:native
 bun run test:e2e
 ```
 
-`bun run validate` is the main gate. It covers typechecking, linting, format checks, maintainability checks, and automated tests for the main project.
+Use `bun run test:e2e` locally before review if you touch command routing, proxy flows, release automation, or workflow wiring and want to reproduce the same CLI e2e lane that PR CI runs.
+
+### Why Did CI Fail?
+
+| Symptom | Likely cause | Fix |
+| --- | --- | --- |
+| `format` fails in PR CI | `bun run format` was skipped locally | Run `bun run format`, recommit, push again |
+| `lint` fails in PR CI | `validate` now uses read-only `lint` | Run `bun run lint:fix`, then rerun `bun run validate` |
+| `test` fails in PR CI but `validate` passed | The failure is in `test:slow` or `test:e2e` | Run `bun run validate:ci-parity` locally |
+| Checks stay queued for >10 min | Self-hosted runner is offline | Wait for maintainer intervention; rerunning usually does not help |
+| `Dev Release` is red on `dev` after merge | Release-only failure or publish problem | Check `Push CI` first to confirm code quality |
 
 If you cannot run the full suite, that is still fine for early or docs-only PRs. Just say what you did run, or what blocked you, in the PR.