> ## Documentation Index
> Fetch the complete documentation index at: https://evalgate.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Risks & controls

> Collaborative RACM for AI risks, controls, safeguards, evidence requests, review authority, and reviewed-scope export.

# Risks & controls

**Status:** Available (Shipped) · **Owner:** Proof / Trust & Review · maturity: [Feature status](https://evalgate.com/docs/platform/feature-status.md)

Open `/proof/risks-and-controls` in the product. The workspace answers: what
could go wrong, what addresses it, which safeguards are mapped, and what
remains unestablished.

This is a collaborative RACM over risks, controls, safeguard bindings,
walkthrough notes, assignments, evidence requests/submissions, conclusions,
findings, risk acceptance, and reviewed-scope export. It is separate from the
control-assurance implementation surface at `/proof/controls`, which owns
receipt-backed prevention claims for tool/schema controls.

## Turn a finding into a regression check

Open a finding in its control's review workspace. Under **What happens next**:

1. Choose **Create regression example**, select the recorded interaction, and enter the exact expected result to propose. The captured input is preserved; the finding description and observed failure are not substituted for the input or desired result.
2. Open **Review proposed example**. An independent human must review the proposed expectation before the existing promotion action can add the case to a check. The proposal retains its source interaction and finding revision.
3. After promotion, use **Open check and run retest** to inspect the check's execution setup and run against the version being assessed. Under **Record a check run as evidence**, select the exact run and record its reconciled receipt. The server checks the stored run, attempts and manifest; retries return the same artifact. Failed outcomes remain failed observations. Promotion alone is not an execution result.
4. Choose **Request retest evidence** to specify the version, environment, required artifacts, evidence owner and reviewer. Submit the recorded artifact through that request and have it reviewed for the actual requirement and scope.
5. The designated control reviewer can use **Review closure**, select accepted retest evidence and record a closure rationale. A stale finding revision, disallowed reviewer or retest linked to another finding is refused.

You can save remediation progress while the fix is being prepared. A proposed
example, promoted case, passing check, accepted artifact, control conclusion and
risk acceptance are separate records; none automatically closes the finding.
Controlled tests do not establish production operation without appropriate
provenance and scope.

## What the matrix shows

| Column | Meaning |
| - | - |
| Risk | Named AI risk with owner |
| Control | Requirement that addresses the risk, with designated reviewer |
| Safeguard | Mapped implementation/profile binding (not manufactured activation) |
| Evidence | Requests and submissions scoped to the control |
| Next | Honest next action (link control, request evidence, review, conclude) |

## Discover controls from a project

**Discover controls from project** extends the existing workspace. It prepares
reviewable mappings from open Repository Intelligence
findings on a published scan. It uses recorded findings rather than inventing
domain-specific risks from filenames.

Select a scanned project, prepare proposals, and open a proposal's inspector.
The inspector shows the exact source revision and recorded file/line references,
distinguishes suggested graph associations from bound relationships, and lists
candidate artifacts with their canonical evaluation/run identities where present.
An artifact's run result does not establish that it applies to the inspected
source revision. Baseline references do not establish baseline acceptance or
release authorization.

The designated reviewer can accept a mapping into an existing control or use
the existing control creation form, prefilled from the proposal. Acceptance
creates the risk, control link, and audit record together; it does not accept
artifacts for evidence requests or conclude control effectiveness. Rejection is
also retained with its rationale and requires an admin or owner for an unassigned
proposal. A new control requires reviewer-defined acceptance criteria; generated
guidance cannot be saved as the criterion. A stale or pruned scan blocks acceptance.
The control workbench links back to its project evidence mappings.

Discovery prepares 20 findings at a time. The inspector bounds graph connections
and candidate artifacts to 100 and discloses truncation. Finding-free scans do
not establish that a project is safe.

The shared contract is `/api/proof/risks-and-controls/discovery`:

* `GET` inspects proposals by `repositoryId`, `proposalId`, or `controlId`, with
  `offset` pagination.
* `POST` accepts an explicit `discover` or `review` command. Review requires the
  proposal's `expectedDigest` and rationale. Identical retries return the recorded
  result; changed retries conflict.
* Generated source TypeScript/Python clients and their `api` CLI expose
  `get_proof_risks_and_controls_discovery` and
  `post_proof_risks_and_controls_discovery`.

Discovery and applicability profiles are merged. The October 17 deployment
record includes schema through migration 0258; authenticated production journey
verification remains separate. See [feature status](https://evalgate.com/docs/platform/feature-status.md)
for current availability and installed-client boundaries.

## Reviewed applicability profiles

The additive profile workflow extends the existing control workbench. In the
matrix, **All controls** searches canonical controls, including those without a
linked risk, repository or evaluation. Counts are matching controls, not risks,
standards mappings or evidence coverage. The original risk-led view is retained.

**Prepare applicability** records why a control applies, is excluded or remains
unresolved for an organization or an existing AI system. A designated reviewer
accepts or rejects that immutable version. Domain and risk tier are separate;
unknown context remains unknown. A low risk tier does not remove obligations or
change CI policy. Recorded source references, implementation locations and
assessment approaches remain independently inspectable.

Organization-authored policies are internally asserted references. External
standards references remain unverified in this writer; it cannot claim verified
clauses, an approved standards crosswalk, complete SC 42 coverage or certification.
Draft references remain drafts. Accepted applicability does not accept an artifact
or establish control effectiveness. An external link or authored revision pin
does not prove an artifact body or current target-version applicability.

Assessment approaches reuse adversarial probes, deterministic assertions,
configuration review, trace/telemetry requirements, provenance artifact review,
resilience exercises and human evidence review. Use the existing evidence
request, submission and reviewer workflow. Human review and organizational impact
assessment cannot be completed by an LLM self-certification. Missing evidence and
unverified fitness remain gaps; this profile writer grants no current evidence
credit or release authorization.

The shared source API is `/api/proof/risks-and-controls/profiles`:

* `GET` lists the control-counted inventory with `q`, `limit` and `offset`, or a
  bounded profile history with `controlId`. The maximum page size is 50.
* `POST` prepares a version using an idempotency key, expected control revision
  and latest profile digest, or reviews an exact profile digest. Changed retries
  conflict. Identity and reviewer authority come from authentication and the
  existing control record.
* Generated source TypeScript/Python clients and their generic `api` CLI expose
  `get_proof_risks_and_controls_profiles` and
  `post_proof_risks_and_controls_profiles`. Source generation is not package
  publication; discover the operations supported by the installed client before use.

Requirement basis currency is shown separately from the historical review and
evidence fitness. Changed canonical requirement material or a replaced accepted
parent baseline requires reassessment of dependent profiles. Renaming a control
does not change its requirement material. Legacy profiles without a frozen basis
remain unverified and readable with their original digests. Authored dependency
pins alone do not establish current evidence credit.

Linked inheritance retains the exact parent profile and canonical control
identity. Reducing inherited obligations requires an explicit exception and
authorized review. Profile versions are retained records; the latest record is
not a complete inventory of every approved scope. Reviewed-scope JSON/XLSX
exports include up to 100 profile records with digests and reviewer attribution,
and disclose truncation. Exported basis text is a redacted presentation; its
digest identifies the original immutable basis, not the redacted bytes.

Project/dataset/release applicability scopes, verified external-source ingestion,
automated evidence collection and full catalog population remain subsequent work.

## Assess evidence for the current scope (candidate)

The current follow-up source adds an optional assessment to the existing
**Review submission** form. Select a reviewed applicability profile, a submitted
artifact, a compatible assessment approach and what that evidence supports.
EvalGate prepares the canonical identities and hashes; reviewers do not copy
them from free-text notes. The default outcome is **Not established**.

The shared submission-review API accepts an optional `assessmentBinding`.
Its read context provides bounded candidate connections, not an assessment
outcome. The designated reviewer's signed-in session is required for human,
hybrid and runtime observation assessments. Automated clients cannot assert
that principal in a request body.

Evidence fitness is independent from applicability, the historical decision,
control effectiveness and release authorization. It can be missing, unverified,
current for the recorded scope, stale, mismatched or failed. All required
approaches and dependent pins must be established before scoped fitness is
current. A policy, configuration, dataset or requirement change reassesses its
dependent bindings while preserving the recorded history. An explicitly
accepted replacement can restore current fitness without deleting its history.

Supported canonical subjects are a document body, an evaluation harness/run
with its captured configuration and dataset, or a correlated runtime policy
observation. A harness commit does not identify a deployed application version;
unresolved system-version joins remain unverified. A runtime observation does
not prove universal enforcement. External links remain references, and
unverified standards references remain unverified.

This candidate requires additive migration 0259 and application deployment.
Source-client generation is separate from registry publication; published SDK
3.14.1 is unchanged. Production acceptance is not established by local fixtures.

## Authority boundaries

* Review, conclude, and close paths require the control’s designated reviewer
  (or an explicit combined-role setting). Submitters cannot self-approve by
  default.
* Risk acceptance requires the recorded risk owner.
* Staging≠production mismatches come from artifact provenance, not free-text
  claim scope.
* Superseded submissions stay readable but are not current acceptance material.

## Evidence and export

1. Request evidence for a control criterion.
2. Submit artifacts against that request (request-scoped replace).
3. Review with loaded artifacts and provenance.
4. Record design/implementation/operation conclusions bound to configuration
   revisions.
5. Export a reviewed-scope snapshot (JSON and XLSX) that freezes limitations and
   evidence IDs.

Guest portals and optional connector collectors remain optional product paths;
do not treat an empty guest invite as a closed control.

## Related reading

* [Connect controls to actual evidence](https://evalgate.com/docs/guides/connect-controls-to-evidence.md)
* [Platform map](https://evalgate.com/docs/platform/platform-map.md)
* [Feature status](https://evalgate.com/docs/platform/feature-status.md)

After a mapping is accepted, the inspector shows the control's real evidence requirements, submitted artifacts and reviewer conclusions. Select a candidate artifact, explain its relationship and explicitly state its claimed applicability to submit it through the existing evidence workflow. Submission does not accept the artifact or establish that the control operates effectively. JSON and spreadsheet reviewed-scope exports include accepted project mapping identities, exact revisions, basis digests, source references and reviewer attribution; exports disclose when the latest100-mapping bound truncates history.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.