// Blog / audit
How to audit agent repo context before code changes
Before an agent changes behavior, audit the context it is about to trust: route, trust state, freshness, evidence, source, and tests.
// direct answer
Short answer
Audit the agent context by checking the routing bundle, trust report, freshness state, evidence records, relevant source files, tests, and repair queue. If any target module is stale, suspect, low-confidence, or security-sensitive, the agent must re-read current code and tests before planning.
Give a coding agent a concrete pre-change audit before it edits behavior-sensitive files.
// real failure mode
The failure mode
An agent can produce a confident plan from outdated summaries and only discover the mismatch after editing the wrong files.
This is especially risky for auth, billing, runtime execution, storage, migrations, secrets, and concurrency.
A pre-change audit turns hidden context assumptions into explicit checks before the diff exists.
// audit workflow
The repo-local fix
Start with the routing bundle to find the module and likely source path.
Read the trust report and freshness map before trusting summaries.
Then inspect evidence, source files, tests, and repair queue items before planning behavior changes.
// concrete example
A runtime change audit
The task asks for a runtime execution fix. The audit finds a module card, but the trust report marks the module low-confidence.
The agent can still use the card to choose files, but it cannot rely on the summary for behavior.
The plan should cite the current runtime source, relevant tests, and any evidence record used during the audit.
// repo proof
Repo proof to inspect
.knowledge/maintenance/routing_bundle.json
The audit starts with a compact route instead of a broad crawl.
- Finding module ownership
- Choosing first source files
- Making behavior claims
.knowledge/maintenance/trust_report.json
The trust gate decides whether summaries are planning input or route hints only.
- Pre-change risk review
- Mandatory source recheck
- Approving a diff
.knowledge/freshness.json
Freshness catches source changes that may invalidate generated context.
- Detecting stale knowledge
- Triggering sync and rebuild
- Ignoring current source
.knowledge/maintenance/repair_queue.json
Repair items are explicit warnings that context needs attention.
- Blocking or narrowing risky edits
- Review handoff
- Treating every repair as a release blocker
// command transcript
Commands and expected checks
node .knowledge/tools/doctor.js - expected
- The agent sees whether the knowledge layer is healthy enough for routing.
- inspect next
- .knowledge/maintenance/quality_report.json
node .knowledge/tools/sync-tracked.js - expected
- Tracked source and knowledge files are compared against freshness state.
- inspect next
- .knowledge/freshness.json and trust_report.json
node .knowledge/tools/generate-pr-summary.js - expected
- A review-facing summary of trust, health, and repair state is generated.
- inspect next
- .knowledge/maintenance/pr_summary.md
Pre-change context gate
// field guide
Pass / fail audit
| Check | Pass | Fail action |
|---|---|---|
| Routing | Module and source path are clear. | Read more source before planning. |
| Trust | Knowledge is trusted or near_trusted. | Use summaries only as route hints. |
| Freshness | No stale target artifacts. | Run sync or rebuild before relying on context. |
| Evidence | Claims have backing files or commands. | Do not quote unsupported prose. |
| Tests | Relevant tests are identified. | Plan must include test discovery or manual verification. |
// guardrails
What the agent should not trust blindly
- For behavior-sensitive work, source and tests beat every knowledge artifact.
- A failed audit should narrow the edit, not create false confidence.
- If evidence is missing, say so in the plan instead of inventing certainty.
// common mistakes
Common mistakes
- Running a broad search and calling it an audit.
- Treating stale summaries as good enough for risky files.
- Not recording repair work after discovering missing evidence.
// quick FAQ
FAQ
Should every small edit run the full audit?
No. The full audit matters most for behavior-sensitive, stale, suspect, or low-confidence areas.
What is the fastest useful audit?
Read the routing bundle, trust report, target source file, and relevant tests. If trust is weak, inspect evidence and repair queue too.
// page-specific next step
Use this page as the pre-change gate
Make the agent show its route, trust state, freshness state, evidence, source files, tests, and open repair items before editing.