# Phase 4 handoff — Code Reviewer + QA + orchestrator wiring

## Done (Phase 4 — 31 Aug 2026)

- [`packages/agents/code_reviewer.py`](../../packages/agents/code_reviewer.py) — reviews generated SFDX against requirements, design, and static analysis.
- [`packages/agents/qa_engineer.py`](../../packages/agents/qa_engineer.py) — test matrix from acceptance criteria + Apex test results.
- [`packages/integrations/static_analysis.py`](../../packages/integrations/static_analysis.py) — mock + PMD CLI providers.
- Apex test runner in [`packages/integrations/salesforce.py`](../../packages/integrations/salesforce.py) — mock + `sf apex run test` CLI.
- Orchestrator split: `implement → review → qa → create_pr` with bounded fix loop (max 3 cycles).
- Artifacts: `review.json`, `review-cycle-{n}.json`, `pmd.json`, `qa-report.json`.
- LLM extensions: `review_code`, `fix_code`, `generate_qa_report` (mock + OpenAI).
- `SalesforceDeveloper.apply_fixes()` — LLM-driven patch pass after failed review.

```text
DESIGN_APPROVE --> IMPLEMENTING --> deploy.json --> REVIEWING --> pmd.json + review.json
                      ^                    |
                      | fix (max 3)        +-- fail --> FAILED
                      +--------------------+
REVIEWING --pass--> TESTING --> qa-report.json --> draft PR --> PR_CREATED
              QA fail --> FAILED
```

## Inputs

| Artifact / field | Source |
|------------------|--------|
| `requirements.json` | Requirement Analyst |
| `design.json` | Solution Architect (allowlist-enforced) |
| `implementation.json` | Salesforce Developer |
| `deploy.json` | Salesforce deploy validate (Phase 3b) |
| `run.artifacts["design_approved"]` | Must be `true` |

## Outputs

| Field | Purpose |
|-------|---------|
| `pmd.json` | Static analysis violations (PMD or mock) |
| `review.json` | Latest code review findings + pass/fail |
| `review-cycle-{n}.json` | Per-cycle review audit trail |
| `qa-report.json` | Test matrix + Apex results + pass/fail |
| `Run.branch_name` / `Run.pr_url` | Draft PR (unchanged from Phase 3b) |

## Env (Phase 4)

```env
STATIC_ANALYSIS_PROVIDER=mock   # mock | pmd
PMD_BIN=pmd
MAX_REVIEW_CYCLES=3

APEX_TEST_PROVIDER=mock       # mock | cli
# cli reuses SALESFORCE_ORG_ALIAS
```

## Pass / fail rules

- **Review:** `passed=false` when any `critical` or `high` finding exists. Fixable blocking findings trigger `apply_fixes` loop (max `MAX_REVIEW_CYCLES`). Exceeded → `FAILED` + Jira comment.
- **QA:** `passed=false` when Apex failures exist or LLM flags mandatory AC gaps. Blocks draft PR.
- **Static analysis:** PMD violations merged into review findings as `category=static_analysis`.

## Live smoke test checklist

1. Set `GITHUB_TOKEN`, `GIT_REPO_URL`, `GIT_PROVIDER=github` in `.env`.
2. Run `python data/dummy-sfdx-repo/scripts/seed_and_smoke_github.py`.
3. Optional: `SALESFORCE_PROVIDER=cli`, `SALESFORCE_ORG_ALIAS=<sandbox>`, authenticated `sf` CLI.
4. Trigger a Jira story through the full pipeline; confirm `review.json`, `qa-report.json`, and draft PR.

## Next (post-Phase 4)

1. `HUMAN_REVIEW` webhook resume after max review cycles (instead of hard fail).
2. Custom PMD / Salesforce Code Analyzer ruleset.
3. Real Apex test class generation (not just stub `@IsTest`).
4. CI pipeline integration (GitHub Actions).
5. Block on medium-severity findings (configurable threshold).

## Constraints (unchanged)

- Lower org / sandbox only — no production deploy.
- Only metadata from approved `design.json`.
- Mock providers remain default for local dev and CI.