Agent-Ready Compliance System for SOC 2: 10 Design Tests

An agent-ready compliance system lets an AI agent discover the current model, inspect authoritative records, take one bounded action, observe a deterministic result, and stop at a human decision. For SOC 2 work, test the system beneath the agent before testing the model. A good prompt cannot make broad write access, hidden rules, stale data, or unreviewable changes safe.

This guide is for a founder or engineer evaluating agentic GRC before starting SOC 2. It tests system design, not model quality. For the operating sequence after you choose a system, use the AI agent workflow for SOC 2.

TL;DR

• Require runtime discovery of record types, fields, relationships, and allowed actions.
• Give the agent read access before write access.
• Use narrow mutations with previews and stale-state checks.
• Reject unknown fields and invalid relationships deterministically.
• Derive due work and readiness from authoritative records.
• Roll back handled multi-record failures and define crash recovery.
• Define human-only approvals, attestations, and judgments.
• Preserve an exact diff plus explicit business dates.
• Keep secrets and high-risk evidence outside ordinary agent context and Git history.
• Test failure, recovery, and model upgrades before relying on the workflow.

What makes a compliance system agent-ready?

An agent-ready system turns compliance work into inspectable state and bounded actions. The agent should not need a giant prompt that repeats the whole data model, guesses which fields are current, or decides which rules matter.

Use this distinction:

Capability	Chat interface	Agent-ready system
Context	Text selected for the conversation	Current records and model discovered at runtime
Actions	Draft an answer	Choose from explicit read, preview, and write actions
Validation	Model reviews its own output	Deterministic domain rules accept or reject it
Concurrency	Usually hidden	Stale revisions or changed state cause a safe failure
Review	Read the response	Inspect the exact proposed record and diff
Authority	Prompt instruction	Separate agent principal plus a human-controlled merge gate
Recovery	Start the chat again	Preserve state, error details, and a safe resume path

An API alone does not supply these properties. The test is whether the complete path constrains an imperfect agent and gives a person enough information to review the result.

The 10 agent-ready compliance system tests

Test	Pass condition	Failure signal
1. Model discovery	The agent can query current types, fields, relationships, and actions	The prompt hard-codes an old schema
2. Authoritative state	One defined source holds current records and long-form work	Chat memory or a copied index becomes a second source
3. Bounded writes	The agent can preview one narrow mutation before applying it	One broad tool can change any record
4. Stale-state rejection	A product write fails when its inspected revision changed	The last writer silently wins
5. Deterministic validation	Product writes reject invalid payloads; validation catches direct edits	The model decides whether its own output is valid
6. Derived workflow	Due work, blockers, and readiness come from shared rules	The agent infers state from labels or prose
7. Failure-safe workflows	Handled failures roll back, while crashes are detectable and recoverable	Partial writes remain hidden or unexplained
8. Human gates	The agent cannot merge, approve itself, or alter the gate	A prompt is the only authority boundary
9. Reviewable history	Reviewers see the final staged tree or commit plus explicit domain dates	A generic activity log hides the change
10. Failure and upgrade path	The agent can report errors, resume safely, and rediscover a new model	Retries duplicate work or old prompts keep writing

Run these tests with a disposable workspace. A sales demo or successful happy path does not show what happens when the agent uses a stale revision, invents a field, crosses its authority, or stops halfway through a workflow. Direct file edits bypass product write checks and can create invalid state, so they require validation and exact diff review before merge.

1. Make the model discoverable at runtime

Ask the system to describe its installed record types, required fields, relationships, allowed values, current records, and available actions in a machine-readable form. Then change or upgrade the model and run the same query again.

A passing system lets the agent adapt to the workspace it is changing. A failing system expects the prompt to remember field names, relationship rules, and status meanings. That prompt becomes wrong when the model changes.

For FileGRC, an agent can start with:

npx filegrc program-path --next --json
npx filegrc types --json
npx filegrc guide control --json
npx filegrc list control --workflow --json

These commands separate model discovery, current records, and derived workflow state. The output does not give the agent authority to change anything.

2. Keep one authoritative state

Name the source of truth for structured records, long-form work, relationships, and history. Search indexes, embeddings, chat transcripts, and cached summaries may help retrieval, but they should be reproducible from the authoritative state rather than becoming parallel program records.

For a file-based GRC workspace, JSON can hold facts the engine validates and connects, Markdown can hold long-form work, and Git can supply revision history. Domain dates still belong in records because a commit timestamp does not say when management approved a policy, performed a review, or collected evidence.

Test this by changing one authoritative record and asking every interface for the resulting workflow state. The browser, CLI, CI, and agent should return the same rule outcome.

3. Require bounded writes and previews

Start the agent with read-only access. Add one narrow write only after its proposed output matches the program rules.

For an ordinary record, the write path should support:

1. inspect the current record and revision;
2. generate a model-shaped mutation;
3. preview the result without writing;
4. apply the intended payload;
5. run validation;
6. inspect the exact diff.

npx filegrc get CONTROL_ID --mutation > control-update.json
# Edit only reviewed fields.
npx filegrc preview-mutation control-update.json --json
npx filegrc update control CONTROL_ID control-update.json --json
npm run validate
git status --short
git ls-files --others --exclude-standard -- data/
git diff -- data/
# After human review, stage the exact changed path reported by Git.
git add -- data/controls/CONTROL_ID.json
git diff --cached -- data/

A preview is advisory unless the system binds the reviewed payload, expected revisions, model version, and operation to the later write. FileGRC previews do not produce that binding, so a person must review the exact post-write diff and the final staged tree or commit before merge. A preview also does not prove that its claims are true or that evidence is sufficient.

4. Reject stale and invalid work

The system should fail closed when:

• another change landed after the agent inspected a record;
• the payload contains an unknown field;
• an ID points to the wrong record type;
• a required relationship is missing;
• a lifecycle action is not allowed in the current state;
• a path escapes the workspace.

Ask the agent to submit each failure in a test workspace. A useful error names the rejected field, relationship, revision, or prerequisite and tells the agent what it may inspect next. It should not silently discard fields, overwrite newer work, or turn a failed write into a success summary.

5. Derive workflow state instead of asking the agent to infer it

Compliance state often depends on several records. A control may look complete while a required policy is inactive, an evidence source is missing, or a recurring obligation is blocked. Do not make the agent reproduce those rules from prose.

The system should calculate:

• current program stage and next actions;
• due, blocked, and overdue work;
• allowed actions for the current record;
• program, period, and audit readiness;
• stale reviews after material source changes;
• missing evidence or population coverage.

Derived state should remain disposable and reproducible. Persist an action item only when it is a real assigned program record, not because an agent needed a temporary to-do list.

6. Make multi-record failures recoverable

Some actions must create or update a related set of records. A personnel start, incident, policy activation, or completed recurring obligation may need an event, action items, evidence references, dates, and review facts.

Use a purpose-built operation that validates the full set before writing. FileGRC attempts to roll back a handled batch failure, but restoration can also fail. A process kill or power failure can bypass rollback, so this is not a crash-atomic guarantee.

Test both an injected exception and a hard process termination. After either failure, restart validation, inspect Git status and diffs, and recover the workspace to a known valid commit before retrying the operation.

Generic create and update endpoints are useful for ordinary records. They are not a substitute for a domain operation when the workflow has cross-record rules.

7. Put human authority outside the agent

Write an action matrix before enabling writes:

Level	Agent may do	Required boundary
Read	Inspect records, relationships, due work, and checks	Read-only workspace access
Draft	Scaffold a record, propose Markdown, prepare a mutation	Person reviews every source fact
Apply reviewed facts	Submit an approved narrow payload	Isolated branch or worktree; agent cannot push or merge the protected authoritative branch
Human decision	Approve policy, attest, accept risk, conclude a control result	Named person reviews the final commit and controls merge
CPA judgment	Select samples, test controls, evaluate evidence, issue the report	Independent CPA firm performs the examination

NIST’s AI Risk Management Framework Core calls for organizations to define roles for human-AI configurations and human oversight. In a SOC 2 workflow, the enforcement point matters as much as the written rule. Do not expose an approval action to an agent and rely only on a prompt telling it not to call the action.

Direct file access can bypass a hidden CLI action. Prompts, validation, previews, and diffs are safeguards, not authority controls. Give the agent a separate account or credential that cannot push or merge the protected authoritative branch, approve its own change, change required checks or branch protection, or use an administrator bypass. Keep its writes on an isolated branch or worktree and let a person control the final merge. Run required merge-time checks from trusted configuration, and require a separate owner to review changes to CI workflows, validation scripts, and their dependencies.

8. Preserve reviewable changes and business dates

Reviewers need the proposed before-and-after state, not only a statement that the agent “updated the control.” Inspect untracked, unstaged, and staged files, then review the final commit before merge. A plain git diff omits untracked files and may omit staged work. If an agent can write files, branch rules should require a human review and passing validation before merge.

GitHub documents required review and status-check options for protected branches. A repository may use different controls, but the test stays the same: can a reviewer see and gate the exact latest change?

Keep event, approval, collection, completion, and verification dates in the domain records. Git history documents when the repository changed, which is a different fact.

9. Bound evidence and agent context

Do not give an agent every artifact merely because it can read the repository. Classify what may enter:

• ordinary program records and public framework text;
• internal policies and procedures;
• fixed evidence allowed by repository access and retention rules;
• restricted evidence that stays in an approved source system;
• forbidden material such as plaintext credentials, private keys, tokens, or personal data that may need erasure.

Use references and collection records for material that should not enter Git or the model context. Record the source, scope, collection date, covered period, query or report parameters, and review result. The source system still operates the control and produces the evidence.

10. Test failure, recovery, and upgrades

Give the agent a test plan that includes:

1. an invalid field;
2. a stale expected revision;
3. a disallowed lifecycle action;
4. a handled batch error and a hard process termination;
5. a validation failure after a proposed change;
6. a rejected human approval;
7. an upgraded data model;
8. a retry after another change lands.

Handled errors should return a machine-readable result, leave no unintended write, and name the next safe action. A hard termination may not return an error, so require restart validation, Git inspection, and a documented recovery to a known valid state. After a model upgrade, make the agent rediscover the model rather than replaying a stored payload.

A resumable agent names what succeeded, what failed, what changed, and which human or command is needed next. It does not keep retrying a consequential write until something accepts it.

How FileGRC supports agent-ready SOC 2 work

FileGRC is a Git-native GRC workspace for SOC 2 work. JSON holds structured records, Markdown holds long-form work, and Git supplies the change history. The repository is the authoritative program record. The browser and CLI use the same model and domain rules.

Agents can discover the model, inspect records and relationships, scaffold ordinary records, preview bounded mutations, run recurring and event workflows, validate the workspace, report readiness blockers, and prepare an evidence packet for management review. CLI writes change files but do not create Git commits, so the normal diff and review path remains visible.

FileGRC does not collect evidence from external systems, approve management decisions, decide whether evidence is sufficient, or perform the examination. Starter records are proposals. People must tailor them to the company, operate the controls, review the changes, and make the decisions assigned to them.

The FileGRC source and setup guide documents the current model and commands. Start an evaluation with read-only discovery, run the ten failure tests in a disposable workspace, and grant one bounded write only after the proposed output and recovery behavior pass review.