To review AI agent file changes, compare the proposed result with the version the agent started from, check whether the live files changed meanwhile, and inspect the accepted files after applying. A useful Change Set groups the proposed edits and their origin into one reviewable result.
Imagine an agent updating a weekly research report, changing a CSV, and adding source notes. The reviewer needs to see those three operations together, understand the evidence behind the new claims, and keep unrelated edits out of the accepted workspace.
Development preview: the local workflow
This 27-second silent recording runs the actual native Core CLI through a verification viewer. It uses synthetic files and deterministic simulated agent edits.
The unreleased development candidate was built from commit 74fde6f. Its repair is under review in draft PR #90. The viewer is verification tooling, not the shipping Folderbase App, a live model run, a Cloud workflow, or an OS isolation demonstration.
Public Core 0.7.2 still has the added-file apply limitation described in this guide. This candidate recording does not mean the fix has shipped.
Text transcript
- Initialize: preview and initialize an existing folder while preserving its original brief.
- Propose: check out the shared subtree, modify the brief, and add a report. The source remains unchanged during proposal creation.
- Accept and replay: apply the proposal, then replay the same operation and receive already_applied.
- Continue: start a fresh session from the accepted report and retain its Object ID.
- Protect a newer edit: an owner changes the report after the agent’s proposal. The stale apply returns an edit_edit conflict and preserves both inputs.
- Recover: restore the first report to a separate path. A second restore returns would_overwrite. The restored bytes and private sibling remain unchanged, and final validation passes.
Keep three states visible
The base is the input version supplied to the agent. The proposal is the result returned from its working copy. The live state is what the owner currently has. Recording all three makes a stale assumption visible.
For example, the agent changes the report’s conclusion while a person corrects the same paragraph. A proposal that was valid against its base now needs a decision. Keep the person’s current file and the agent’s proposal available while resolving the overlap.
| State | What the reviewer needs |
|---|---|
| Base | Exact version and selected input files |
| Proposal | Added, modified, moved, and removed files |
| Live state | Edits made after the agent started |
| Accepted result | Verified files and a recorded version |
Read the summary before the diff
Start with the task, the affected paths, and the type of change. A three-file report update should not unexpectedly modify a credentials file or reorganize the source directory. Ask for a reason for removals and moves, because they can break references elsewhere.
For an ordinary pair of text-file copies, Git can show a diff without creating a repository. The command below compares two existing files and changes neither. Exit status 1 means differences were found; inspect errors separately.
git diff --no-index -- base/weekly-report.md proposal/weekly-report.mdVerify the work behind the words
A clean text diff can still introduce an unsupported claim. Follow the cited sources and check that the edited conclusion matches the data. In a CSV, inspect changed cells, row counts, headers, and any identifiers used by another tool.
Give the agent a bounded output contract before the run: the files it may create, the inputs it may read, and the changes requiring review. Keep that contract small enough that the operator can assess it without reconstructing the entire task.
- Does the result answer the requested question?
- Can each material claim be traced to the supplied source?
- Did the agent change a formula, unit, date range, or identifier?
- Were any files removed or moved unexpectedly?
- Is unrelated or private material present in the output?
Review binary files in the applications that understand them
A file hash tells you that bytes changed. It does not explain a spreadsheet formula, a slide layout, or a PDF annotation. Pair a file-level change summary with the native application, a rendered preview, or a format-specific comparison.
For a spreadsheet report, open the proposed workbook and check formulas and charts as well as displayed values. For a PDF, review page count and the rendered pages. Keep the original available during review. Live application databases need an application-consistent export or backup procedure before they become stable review inputs.
Separate review from execution containment
A local review convention cannot stop a process that already has permission to overwrite the source directory. Keep untrusted execution behind an appropriate OS or runtime boundary and supply only the files and credentials it needs.
Folderbase’s local model depends on cooperating tools. Treat scoped records and review controls as part of a workflow; evaluate the actual runtime boundary before granting access.
Verify acceptance and rehearse recovery
Check the live state again before accepting the proposal. After application, reopen the changed files, confirm the accepted version, and ensure another session can read the expected result. An assessment marked clean is not proof that application succeeded.
Atomic publication of a version and simultaneous visibility to every ordinary file reader are different guarantees. State the exact behavior your tools provide. Before relying on the workflow, recover a previous result in a test workspace and confirm that the recovered files are usable.
Folderbase’s current release boundary
Core 0.7.2 can assess an added-file Change Set as clean and then fail during application. Later investigation of issue #78 found that a new file may already exist after the error. Inspect the live files and preserve the proposal before deciding how to recover or retry. The complete new-file write-back journey is blocked until a fixed release is available.
Start with the local setup quickstart. For write-back evaluation, pin your Core version and use the documented capabilities and known issues. Keep proposals available when application fails; a failed apply should never be presented as completed work.