Add review skill and make review stage mandatory in AGENTS.md

- Add .agents/skills/review/SKILL.md with a required review checklist covering
  project rules, model client rules, pipeline rules, XML rules, and test rules.
- Update AGENTS.md with a dedicated 'Review Stage Rules' section that makes
  review mandatory and maps confidence thresholds to XML generation behavior.
- Add review skill to the skills reference.
- Add .ruff_cache/ to .gitignore and keep agent XML templates out of the '*.xml' ignore rule.

.agents/skills/review/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: review
+description: Use this skill when reviewing code, tests, or design decisions in the odoo_ocr project before approving or committing changes.
+---
+
+# Review Skill
+
+Use this skill whenever you are asked to review code, tests, architecture, or any proposed change in the `odoo_ocr` project.
+
+## Required Review Checklist
+
+Before approving any change, verify the following. If any item fails, flag it and request a fix.
+
+### 1. Project Rules Compliance
+
+- [ ] New code lives under `src/odoo_ocr/`.
+- [ ] Pydantic schemas are updated or added before business logic changes.
+- [ ] Type hints are present; `mypy --strict` passes or only has justified exceptions.
+- [ ] No hardcoded secrets, endpoints, or model names outside of `config.py` / settings.
+- [ ] Logging is used; model calls log latency and token usage.
+
+### 2. Model Client Rules
+
+- [ ] Model calls go through `BaseVLMClient` (Ollama or llama.cpp).
+- [ ] Extraction/review prompts force JSON output; no regex scraping of prose.
+- [ ] Retries use exponential backoff for transient failures.
+- [ ] Cache keys include prompt + image hash + model + temperature.
+
+### 3. Pipeline Rules
+
+- [ ] Every invoice must pass through the **review stage** before XML generation.
+- [ ] `ReviewResult` includes `valid`, `confidence`, and `issues`.
+- [ ] Confidence thresholds from `config.yaml` are respected:
+  - `>= 0.90`: generate final XML.
+  - `0.75–0.89`: generate XML with human-review flag.
+  - `< 0.75`: do not generate final XML; emit sidecar JSON only.
+- [ ] The original image is passed to the review VLM alongside the extracted JSON.
+
+### 4. XML Rules
+
+- [ ] Generated XML is parseable by `lxml`.
+- [ ] Required Odoo records are present: `res.partner`, `account.move`, `account.move.line`.
+- [ ] Tax records are deterministic by rate/type.
+- [ ] External IDs are sanitized and stable.
+
+### 5. Test Rules
+
+- [ ] New modules have tests under `tests/`.
+- [ ] Model calls are mocked in unit tests (use `FakeVLMClient` from `conftest.py`).
+- [ ] `pytest`, `ruff check src tests`, and `mypy src/odoo_ocr --strict` all pass.
+
+## Review Output Format
+
+When asked to review, produce a concise report with:
+
+1. **Summary**: what changed and whether it looks correct.
+2. **Checklist results**: pass/fail per section above.
+3. **Required fixes**: blockers that must be addressed.
+4. **Suggestions**: non-blocking improvements.
+5. **Verdict**: `APPROVE`, `APPROVE WITH NITS`, or `REQUEST CHANGES`.
+
+If the user did not ask a specific question, default to reviewing the most recent changes in the working tree or the file(s) they mentioned.

.gitignore

@@ -47,6 +47,7 @@ dmypy.json
 htmlcov/
 .tox/
 .nox/
+.ruff_cache/
 
 # Project-specific
 out/
@@ -54,5 +55,6 @@ output/
 *.xml
 !tests/fixtures/*.xml
 !templates/*.xml
+!src/odoo_ocr/.agents/skills/odoo-xml-import/templates/*.xml
 .cache/
 ~/.cache/

AGENTS.md

@@ -69,13 +69,26 @@ Input File
 
 ## Data Flow Rules
 
-1. Every invoice must produce:
+1. Every invoice must pass through the **review stage** before XML generation. The review model compares the original image with the extracted JSON and produces a `ReviewResult`.
+2. Every invoice must produce:
    - A Pydantic `ExtractedInvoice` object.
    - A review result (`ReviewResult`) with confidence score and issue list.
    - An Odoo XML file (unless blocked by low confidence).
    - A sidecar JSON file with metadata, timings, and confidence.
-2. If review confidence is below the configured threshold, mark the invoice for human review and do not generate final XML (or generate a draft with a warning flag).
-3. Never send invoice data outside the local model endpoints.
+3. If review confidence is below the configured threshold, mark the invoice for human review and do not generate final XML (or generate a draft with a warning flag).
+4. Never send invoice data outside the local model endpoints.
+
+## Review Stage Rules
+
+1. The review stage is **mandatory**, not optional.
+2. The review VLM must receive both the original invoice image and the extracted `ExtractedInvoice` JSON.
+3. The review prompt asks the model to verify field presence, arithmetic, and consistency.
+4. The `ReviewResult` must include a confidence score between 0.0 and 1.0 and a list of issues.
+5. XML generation must respect the confidence thresholds in `config.yaml`:
+   - `confidence >= 0.90`: generate final XML.
+   - `0.75 <= confidence < 0.90`: generate XML with a human-review flag.
+   - `confidence < 0.75`: do not generate final XML; emit sidecar JSON only.
+6. See skill `review` for the full review checklist.
 
 ## Odoo XML Target
 
@@ -104,3 +117,4 @@ Agents should load the relevant project skills from `.agents/skills/`:
 - `odoo-ocr-pipeline` — when implementing classifier, branches, OCR, extraction, or review.
 - `odoo-xml-import` — when generating or validating Odoo XML.
 - `local-vlm-client` — when writing model clients or prompts.
+- `review` — when reviewing code, tests, or design decisions before approving changes.