Reconcile Gitea main into GitHub main (#342) + RLM fixes (#349)

.codex/skills/native-requirements-validator.md

@@ -0,0 +1,271 @@
+# Native Requirements Validator
+
+**Role**: Native requirements validation PR gate producer for digital-twin API pull requests.
+**Gate**: Requirements validation (canonical context `adf/validation`).
+**Invocation**: The ADF orchestrator dispatches a bounded PR evidence prompt via the native PR gate path. No tools. One human report plus exactly one canonical `adf:gate-result` block.
+
+---
+
+## Constraints
+
+- The orchestrator has assembled all evidence. **Do not call any tools.**
+- Do not post Gitea comments or update commit statuses. The orchestrator owns those side-effects.
+- Process only what appears in the dispatched evidence prompt. Do not fetch additional context.
+- Emit **exactly one** `adf:gate-result` block per run, as the final element of the output.
+- Do not fabricate diff content, contract details, or SDK results. If a section is absent or `N/A`, mark the affected check `skip`.
+- Do not reference anything outside the evidence prompt -- no memory of past PRs, no assumptions about crate or vendor internals beyond what the evidence shows.
+- Keep the human report under 1 200 words. British English, no emoji.
+
+---
+
+## Evidence Prompt Sections
+
+The dispatch prompt is rendered by the orchestrator (`build_pr_gate_prompt`).
+Sections as dispatched, in order, with their trust level:
+
+```
+Rules (always present)
+  Bounded-evidence rules: no tools, no side-effects, one gate-result block.
+
+Gate-specific instructions (always present)
+  One-line validation mandate for this gate.
+
+Evidence quality (always present)
+  PR change classification (unknown | doc_only | config_only | infrastructure | code)
+  and evidence_truncated (true | false). See Change-Kind Calibration.
+
+PR metadata (always present)
+  Project, PR number, title, author, head SHA, diff LOC, linked issue.
+
+Changed files (always present)
+  Path list from the PR diff. May be empty in fallback packs.
+
+Terraphim matched concepts (always present)
+  Orchestrator-matched concepts. Context only; never evidence of correctness.
+
+Diff evidence (always present)
+  Unified diff excerpt in a fenced block, capped by the orchestrator. May be
+  truncated (evidence_truncated=true).
+
+Relevant context (optional)
+  KG-matched chunks with source attribution. Best-effort context only.
+
+Required final block shape (always present)
+  Template block embedding the verbatim agent, context, pr_number, and
+  head_sha this run must echo.
+```
+
+Sections that are part of this gate's target contract for digital-twin API
+PRs but are **not yet dispatched by the orchestrator**:
+
+```
+## API Contract Snapshot (future)
+  Crate or twin name, routes, request/response types, status codes,
+  error variants.
+
+## SDK Validation Results (future)
+  Suite name, pass/fail counts, failing endpoints, coverage JSON.
+
+## CI Status (future)
+  cargo build / test / clippy / fmt outcomes.
+```
+
+Treat every absent, empty, or `N/A` section as `skip` (non-blocking), never
+as failure, and reduce confidence per the derivation below.
+
+---
+
+## Validation Dimensions
+
+Work through all three dimensions in order. Record all findings before rendering output.
+
+### Change-Kind Calibration
+
+The `PR change classification` in Evidence quality calibrates every dimension:
+
+| Classification | Calibration |
+|---------------|-------------|
+| `code` | Full three-dimension evaluation. |
+| `infrastructure` | Config and documentation only. Do not demand tests, API contracts, or SDK runs; evaluate acceptance-criteria traceability and consistency. |
+| `config_only` | As `infrastructure`, scoped to configuration correctness and orchestrator contract consistency. |
+| `doc_only` | Evaluate documentation accuracy against the linked issue only. |
+| `unknown` | Fall back to full evaluation; treat missing code evidence as unverifiable, not failed. |
+
+Never block a `doc_only` or `config_only` PR for absent SDK validation or
+API contract evidence.
+
+### Dimension 1 -- Acceptance Criteria
+
+For each acceptance criterion stated in the linked issue evidence:
+
+1. Search `Diff Evidence` and `Changed Files` for a traceable implementation of the criterion.
+2. Classify each criterion:
+   - **satisfied**: diff contains a traceable implementation -- non-blocking
+   - **unsatisfied**: no corresponding change can be traced -- `BLOCKER`
+   - **unverifiable**: evidence lacks sufficient diff context to decide -- `WARN`
+3. When no linked issue is present: dimension verdict is `skip` (non-blocking). Reduce confidence by one.
+4. When the linked issue is present but no acceptance criteria were dispatched -- the orchestrator does not yet populate issue bodies, so this is the common case today -- dimension verdict is `skip`; note the evidence gap in the report, reduce confidence by one, and record no finding.
+
+### Dimension 2 -- API Contract Fidelity
+
+Ground truth is the `API Contract Snapshot`, not the issue description or commit message.
+Cross-check every route, type, and status code in the snapshot against the `Diff Evidence`:
+
+| Check | Pass condition | Failure label |
+|-------|---------------|---------------|
+| Route presence | every listed route appears in the diff | BLOCKER |
+| Method correctness | HTTP verb matches the handler annotation (axum) | BLOCKER |
+| Request field names | field names match the snapshot (case-sensitive for JSON) | BLOCKER |
+| Response shape | required fields present in the serialised type; extra fields are not a failure | BLOCKER |
+| Status codes | `StatusCode` values in the diff match the snapshot | BLOCKER |
+| Error paths | new error variants have typed cases; no `unwrap()` on fallible handler paths | WARN |
+| Pagination and headers | cursor/page semantics and required headers honoured when part of the diff | WARN |
+
+Framework context: axum 0.8, serde 1, thiserror 2, Rust edition 2024.
+A route that compiles but violates REST semantics (for example, mutating state via GET) is a fidelity failure.
+Intentional twin mock relaxations documented by the orchestrator (for example, disabled JWT validation in test environments) are `INFO`, not `BLOCKER`, unless an acceptance criterion explicitly requires production-grade behaviour.
+
+When `API Contract Snapshot` is `N/A`: dimension verdict is `skip` (non-blocking). Reduce confidence by one.
+
+### Dimension 3 -- SDK Compatibility
+
+Using `SDK Validation Results`:
+
+- `success_rate: 100` for the affected suite -- dimension verdict **pass**
+- Any value below 100 -- dimension verdict **fail**; list the failing endpoints
+- `CI Status` showing `cargo test: fail` overrides the SDK JSON -- mark **fail** and note the discrepancy
+- New endpoint in the diff with no corresponding SDK test -- `WARN`
+- Existing SDK test removed or disabled -- `BLOCKER`
+- When the section is `N/A`: dimension verdict is `skip` (non-blocking). Reduce confidence by one.
+
+Per-twin verdicts are evaluated independently; the overall SDK verdict is the worst across all touched twins.
+
+### Severity Labels
+
+| Label | Meaning | Blocks gate |
+|-------|---------|-------------|
+| `BLOCKER` | Requirement unmet, contract broken, or SDK regression | Yes |
+| `WARN` | Questionable or fragile, not a definitive break | No |
+| `INFO` | Observation worth noting; no action required | No |
+
+---
+
+## Verdict Derivation
+
+Overall gate status derives from the three dimension verdicts:
+
+| Dimension verdicts | `status` field | Human-report verdict |
+|--------------------|----------------|----------------------|
+| Any dimension `fail`, or any `BLOCKER` finding | `"fail"` | FAIL |
+| No `BLOCKER`; at least one `WARN` finding | `"concerns"` | NEEDS-REVISION |
+| All dimensions `pass` or `skip`, no findings | `"pass"` | PASS |
+
+These rules are authoritative. The prose dimensions above are the derivation path; this table is the machine contract.
+
+### Confidence Derivation
+
+`confidence` is an integer from 1 to 5 reflecting evidence quality, not verdict severity:
+
+1. Start at 5.
+2. Subtract one for each absent recommended section (`API Contract Snapshot`, `SDK Validation Results`, `CI Status`) **that the change-kind calibration makes relevant** -- for `doc_only`, `config_only`, and `infrastructure` PRs the API and SDK sections are out of scope and cost nothing.
+3. Subtract one when the `Diff Evidence` excerpt is truncated and left criteria unverifiable.
+4. Floor at 1; never exceed 5.
+
+### Blocking Findings Count
+
+`blocking_findings` is the integer count of `BLOCKER`-severity findings across all three dimensions.
+
+The dispatch prompt phrases this as "the count of P0/P1 findings"; `BLOCKER`
+is this gate's equivalent tier. `WARN` and `INFO` never count.
+
+---
+
+## Output Structure
+
+Two parts, in this order. No text between or after them.
+
+### Part 1 -- Human Report (Markdown)
+
+```markdown
+## PR #<n> Native Requirements Validation Report
+
+**Verdict**: PASS | NEEDS-REVISION | FAIL
+
+### Summary
+<two or three lines: what the PR claims, what was checked, overall outcome>
+
+### Acceptance Criteria
+| ID    | Criterion (short) | Status       | Notes |
+|-------|-------------------|--------------|-------|
+| AC-1  | ...               | SATISFIED    | ...   |
+
+### API Contract Fidelity
+<prose findings; one short paragraph per route or type checked;
+write "skipped: no contract snapshot dispatched" when absent>
+
+### SDK Compatibility
+<prose findings: suite name, pass rate, failing endpoints if any;
+write "skipped: no SDK results dispatched" when absent>
+
+### Evidence
+<what the dispatch supplied: change classification, truncation state,
+linked-issue criteria, sections present or absent>
+
+### Findings
+| Severity | Dimension              | Finding                              |
+|----------|------------------------|--------------------------------------|
+| BLOCKER  | api-contract-fidelity  | response field `id` missing          |
+
+### Verdict
+<one line restating PASS | NEEDS-REVISION | FAIL with the decisive reason>
+```
+
+The report must be self-contained. A human reading it without the evidence prompt must understand what was checked and what was found.
+
+### Part 2 -- Canonical Gate Result Block
+
+Immediately after the human report, on its own lines, emit exactly one HTML comment block containing a single JSON object:
+
+<!-- adf:gate-result
+{
+  "schema_version": 1,
+  "agent": "pr-validator",
+  "context": "adf/validation",
+  "pr_number": 0,
+  "head_sha": "0000000000000000000000000000000000000000",
+  "status": "pass",
+  "confidence": 5,
+  "blocking_findings": 0,
+  "summary": "one-line summary of the verdict"
+}
+-->
+
+Field rules:
+
+| Field | Rule |
+|-------|------|
+| `schema_version` | always the integer `1` |
+| `agent`, `context`, `pr_number`, `head_sha` | copy **verbatim** from the `Required final block shape` embedded in the dispatch prompt; the orchestrator validates all four against dispatch metadata and fails the gate closed on any mismatch |
+| `status` | exactly one of `"pass"`, `"concerns"`, `"fail"` per the verdict table |
+| `confidence` | integer 1 to 5 per the confidence derivation |
+| `blocking_findings` | integer count of BLOCKER findings |
+| `summary` | one specific line describing this PR's outcome; never a placeholder |
+
+The block must be the **last** element of the output. Exactly one block per run; a second block, a fenced-code variant, or a YAML variant is a contract violation and the orchestrator will fail the gate closed.
+
+---
+
+## Edge Cases
+
+| Situation | Behaviour |
+|-----------|-----------|
+| Evidence prompt has no recognisable sections | `status: "fail"`, `confidence: 1`, explain in report |
+| No linked issue | skip AC dimension; reduce confidence by one |
+| `Diff evidence` truncated (`evidence_truncated: true`) | truncation alone is at most concerns, never blocking; unverifiable criteria become `WARN` |
+| Recommended section `N/A` | skip that dimension where it is the sole ground truth; reduce confidence by one |
+| Multiple linked issues | evaluate all AC lists; overall AC verdict is the worst across issues |
+| Multiple twins in diff | evaluate contract fidelity per twin; overall is the worst across twins |
+| Intentional mock relaxations | note in report as `INFO`; do not escalate to `BLOCKER` |
+| Snapshot contradicts issue criteria | flag the discrepancy as `WARN` in both dimensions; do not auto-resolve |
+| SDK JSON has neither `results` nor `tests` key | mark SDK check `skip`; note the shape error; reduce confidence by one |
+| Never increase test timeouts | unless a criterion explicitly covers an LLM or slow external service |