Expose paginated finding evidence for agent-assisted remediation

[dweinstein]

What & why

Assessment findings currently discard the scan's evidence, so an agent can read general remediation guidance without seeing the observed settings, affected files, or referenced code locations that would help it target a fix.

Add include_evidence to get_assessment_findings, scoped by check_ids. Responses include evidence rows, field definitions, and available code-location data alongside full developer recommendations. Evidence defaults to 20 rows per finding, supports evidence_offset / evidence_limit (maximum 100), and reports totals and continuation metadata. Only locations referenced by the returned page are fetched. Missing location data is reported explicitly.

For example, a high-severity insecure-network finding can now expose the observed base-config cleartext setting and separate domain exceptions, giving an agent specific configuration to inspect. The workflow guidance explains how to retrieve evidence and check the same finding against an explicitly selected new scan. The MCP tools remain read-only; source changes and new scans use the agent's other capabilities.

The README keeps user-facing examples under Platform prompts. Evidence integration details and live-audit instructions live in docs/evidence.md, linked from Development.

The findings response also preserves large numeric evidence values on the wire. The SDK's typed-output validation currently rounds such values through float64; a narrow findings registration helper validates a disposable copy and serializes the original JSON. Input validation, output schemas, logging, and compact default tables are retained. The existing jsonschema-go dependency becomes direct without a version change.

Validation:

• Full tests with go test -race ./..., go vet ./..., and go build ./....
• CI's pinned golangci-lint v2.12.2: zero issues.
• MCP schema snapshot, filtering, cache isolation, pagination, errors, and raw-wire numeric precision tests.
• Opt-in live audit across 31 affected scored findings on three apps; 30 supplied evidence. Median evidence response ~1,054 estimated tokens; largest default page ~7,937. A 616-row finding starts at ~1,330 tokens; all rows remained retrievable across seven pages, totaling ~34,971 tokens. Pagination bounds the initial read, not total context if every page is retained. Estimates use bytes/4 for one representation, not a model tokenizer; clients including both representations roughly double the payload.

The live audit is disabled in normal test runs, reads credentials only from the process environment, and reports aggregate measurements without app identities or raw evidence. Tokens and live captures are excluded from this commit. This validates evidence retrieval and response sizes; a full coding-agent patch/test/rescan workflow has not been evaluated.

Self-review

• Tests added/updated
• Ran it locally
• Reviewed own diff
• Edge cases considered