# GrantFlow Trust Report — What It Means and What It Does Not

## What trust_summary is

Every completed job exposes a `trust_summary` block inside `GET /status/{job_id}/quality`.
It synthesises grounding, critic, HITL, citation, and export-contract signals into a single
buyer-facing verdict so proposal teams can decide whether to export without reading the full
quality payload.

```json
{
  "trust_summary": {
    "verdict": "export_ready",
    "export_ready": true,
    "grounded": true,
    "critic_passed": true,
    "hitl_resolved": null,
    "citations_present": true,
    "blocking_reasons": [],
    "governance_flags": {
      "open_high_severity_finding_count": 0,
      "open_finding_count": 0,
      "hitl_pending": false,
      "export_contract_passed": true,
      "grounding_risk_level": "low"
    }
  }
}
```

## Verdict values

| Verdict | Meaning |
|---|---|
| `export_ready` | Job done, no open high-severity findings, export contract passed, grounding OK (or not evaluated). Safe to export. |
| `needs_review` | Job done but one or more quality signals are amber. No blocking issues, but a human reviewer should check before export. |
| `needs_revision` | Open high-severity critic findings, HITL pending, or job ended in error. Do not export without resolving the blocking_reasons. |
| `incomplete` | Job has not reached a terminal status yet. Poll again. |

## What GrantFlow verifies (production-ready)

| Signal | Where it comes from | Verified by GrantFlow |
|---|---|---|
| Donor-aware preflight | `/generate/preflight` checks RAG readiness, grounding policy, doc inventory | Yes |
| Workflow completion | Job reaches `done` status (not `error` or `pending_hitl`) | Yes |
| Critic rule checks | Static rule engine runs against generated ToC and logframe | Yes |
| LLM critic findings | LLM-based reviewer flags structural and evidence issues | Yes, when `llm_mode=true` |
| Citation traceability | Every generated claim is linked to a retrieval source or flagged as fallback | Yes |
| Grounding gate | Runtime check: retrieval-grounded citations vs. fallback rate | Yes |
| Export contract | Donor-specific required sections and sheet structure validation | Yes |
| Idempotency | Same `request_id` + same payload → same job, no duplicates | Yes |
| Audit events | Every lifecycle transition is logged and queryable | Yes |
| HITL checkpoint | Job pauses at designated stages for human review | Yes, when `hitl_enabled=true` |

## What GrantFlow does NOT verify

These items are the responsibility of the operator, gateway, or downstream system.

| Item | Why it is out of scope |
|---|---|
| Factual accuracy of generated text | GrantFlow verifies grounding signals, not factual ground truth. An LLM can produce fluent but incorrect claims even with high retrieval confidence. Human review remains required. |
| Donor submission compliance | GrantFlow validates section structure, not legal or programmatic requirements. A passed export contract does not mean the proposal meets the donor's eligibility criteria. |
| Production OAuth token issuance | GrantFlow exposes onboarding metadata; actual token minting belongs at the gateway or IAM layer. |
| Multi-tenant access control beyond tenant_id | GrantFlow enforces `tenant_id` scoping; broader role-based access control is operator-responsibility. |
| Delivery to donor portals | GrantFlow exports artifacts (Word, Excel, ZIP); submission to external portals is not in scope. |
| PII or data residency compliance | GrantFlow does not inspect content for personally identifiable information or enforce data residency rules. |
| Billing and usage metering | Not implemented. |

## How to read blocking_reasons

Each entry in `blocking_reasons` is a machine-readable token:

| Token | Meaning | Resolution |
|---|---|---|
| `job_not_terminal` | Job still running | Poll again |
| `hitl_pending` | Waiting for human-in-the-loop approval | Resolve the HITL checkpoint |
| `job_error` | Job ended in error | Check job events; retry if transient |
| `open_high_severity_findings:N` | N unresolved high-severity critic findings | Review and resolve findings before export |
| `export_contract_failed` | Donor export contract validation did not pass | Check `export_contract` in the quality payload for missing sections |
| `grounding_failed` | Grounded quality gate did not pass | Review grounding signals; consider re-running with RAG enabled |

## Recommended agent workflow

```
POST /generate/preflight        → verify go_ahead before spending on generation
POST /generate                  → start job with request_id for idempotency
GET  /status/{job_id}           → poll until status in [done, error, pending_hitl]
GET  /status/{job_id}/quality   → read trust_summary.verdict
  if verdict == "export_ready"  → proceed to export
  if verdict == "needs_review"  → route to human reviewer
  if verdict == "needs_revision" → surface blocking_reasons to the proposal team
  if verdict == "incomplete"    → poll again
POST /export                    → export artifacts (requires export:write scope)
```

## Honest limitations

- `grounded: true` means the runtime grounding gate passed, not that the content is factually correct.
- `critic_passed: true` means no open high-severity findings. It does not mean zero findings — medium and low findings may still be open.
- `export_ready: true` is a governance signal, not a legal or compliance certification.
- All quality signals are computed in-process. In high-throughput deployments, consider a dedicated review step before submitting export artifacts to donors.
