docs(contributing): add structured PR process — issue-first, QA cycle, commit format

CONTRIBUTING.md

@@ -84,14 +84,87 @@ Language support is split between two layers:
 4. Add a test case in `tests/test_pipeline.c` for integration-level fixes
 5. Verify with a real open-source repo
 
+## Commit Format
+
+Use conventional commits: `type(scope): description`
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature or capability |
+| `fix` | Bug fix |
+| `test` | Adding or updating tests |
+| `refactor` | Code change that neither fixes a bug nor adds a feature |
+| `perf` | Performance improvement |
+| `docs` | Documentation only |
+| `style` | Formatting, whitespace (no logic change) |
+| `chore` | Build scripts, CI, dependency updates |
+
+QA round fix commits must use the format `fix(scope): address QA round N` (e.g. `fix(pipeline): address QA round 2`).
+
 ## Pull Request Guidelines
 
 - **C code only** — this project was rewritten from Go to pure C in v0.5.0. Go PRs will be acknowledged and potentially ported, but cannot be merged directly.
 - One logical change per PR — don't bundle unrelated features
 - Include tests for new functionality
 - Run `scripts/test.sh` and `scripts/lint.sh` before submitting
 - Keep PRs focused — avoid unrelated reformatting or refactoring
-- Reference the issue number in your PR description
+
+## Pull Request Process
+
+1. **Open an issue first.** Every PR must reference a tracking issue. Accepted formats:
+   - Closing keywords: `Fixes #N`, `Closes #N`, `Resolves #N`
+   - Full GitHub issue URLs: `https://github.com/owner/repo/issues/N`
+   - Bare issue references: `#N` (any `#` followed by a valid issue number)
+   - Sidebar-linked issues (via the GitHub "Development" section on the PR)
+2. Describe what changed and why. Include before/after if relevant.
+3. Test your changes against at least one real project (not the repo itself).
+4. **Run QA review before marking ready.** Run this cycle until a round comes back clean (no confirmed critical or major findings). If the first round is already clean, no further rounds are needed:
+
+   > **Docs-only or trivial PRs:** The QA round requirement only applies when the PR touches logic paths. PRs that only change docs, CI config, or repo metadata skip the check automatically.
+
+   **Step A — Run the QA prompt.** Open a **new** Claude Code (or other AI) session using a top-tier model — **Claude Opus 4.6**, **GPT-5.3 Codex high/xhigh**, or **Gemini 3.1 Pro**. Smaller models (Haiku, Sonnet, etc.) don't produce thorough enough reviews. Paste the prompt below (fill in the placeholders). *(Prompt approach inspired by [@dpearson2699](https://github.com/dpearson2699)'s work in the [VBW project](https://github.com/yidakee/vibe-better-with-claude-code-vbw).)*
+
+   ````text
+   You are a read-only QA reviewer. Do NOT modify files, make commits, or push fixes — report only.
+
+   PR: #<number>
+   Branch: <branch-name>
+
+   1. Review the commits in the PR to understand the change narrative.
+   2. Read all files changed in the PR for full context.
+   3. Act as a devil's advocate — find edge cases, missed regressions, and untested
+      paths the implementer didn't consider.
+
+   Do NOT prescribe what to test upfront. Discover what matters by reading the code.
+
+   Report format — post as **rendered markdown**, not a fenced code block. Use this structure:
+
+   ```
+   ## QA Round N — `branch-name`
+
+   **Model used:** Claude Opus 4.6
+
+   ### Findings
+
+   **[Finding N] SEVERITY: Title**
+   - **What was tested:** ...
+   - **Expected vs actual:** ...
+   - **Severity:** critical / major / minor / nit
+   - **Confirmed vs hypothetical:** ...
+
+   ---
+
+   **SUMMARY: N critical, N major, N minor findings.**
+   ```
+
+   > **Formatting note:** Paste the report as plain markdown text in the PR comment box — do not wrap the entire report in a fenced code block (` ``` `). GitHub renders markdown in comments; wrapping it defeats this and makes the report harder to read.
+
+   **Step B — Fix the findings.** Copy the QA report and paste it into your original working session (or a new session on the same branch). Tell it to fix the issues found. Each QA round's fixes must be a **separate commit** — do not amend previous commits. Use the format `fix(scope): address QA round N`.
+
+   **Step C — Repeat.** Go back to Step A with a fresh session. The new QA round will see the fix commits from Step B and look for anything still missed. Continue until a round comes back clean or only has hypothetical/minor findings.
+
+   **Proving your work:** Paste each round's QA report as a separate PR comment in rendered markdown. Reviewers will cross-reference the reports against the fix commits in the PR history.
+
 
 ## Security