// 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
Check the agent’s context by reviewing the Routing Bundle, confidence report, freshness state, evidence, relevant source files, tests, and unresolved follow-up work. If a target area is outdated, unverified, 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.
// the problem
Agents can plan from context that is incomplete or outdated
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.
// review before editing
Check the agent’s context before changing code
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 unresolved follow-up items before planning behavior changes.
// concrete example
Checking context for a runtime change
The task asks for a runtime execution fix. The check finds a module summary, but the confidence report says it needs review.
The agent can still use the summary to choose files, but it cannot rely on it for behavior.
The plan should cite the current runtime source, relevant tests, and any evidence record used during the audit.
// files you can inspect
Files to check before editing
Some repository-specific files appear only after setup or a health check. Run the documented setup workflow to create routing, confidence, freshness, search, metrics, and PR summary outputs.
.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 confidence report shows whether a summary can support planning or should only help locate source files.
- 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
// commands to try
Commands and expected checks
node .knowledge/tools/doctor.js - what it does
- The agent sees whether the knowledge layer is healthy enough for routing.
- where to look
- .knowledge/maintenance/quality_report.json
node .knowledge/tools/sync-tracked.js - what it does
- Tracked source and knowledge files are compared against freshness state.
- where to look
- .knowledge/freshness.json and trust_report.json
node .knowledge/tools/search-knowledge.js "target module" --scope=project - what it does
- The agent finds scoped local knowledge candidates and then rechecks source/tests.
- where to look
- .knowledge/search/index.json and matched source files
- before you run it
- Search is discovery, not proof.
node .knowledge/tools/generate-pr-summary.js - what it does
- A review-facing summary of trust, health, and repair state is generated.
- where to look
- .knowledge/maintenance/pr_summary.md
Pre-change context gate
// practical reference
Pass / fail audit
| Check | Pass | Fail action |
|---|---|---|
| Fast audit | routing_bundle + target source + tests. | Use for small low-risk edits. |
| Full audit | routing_bundle + trust_report + freshness + evidence + repair_queue + source/tests. | Use for stale, suspect, security-sensitive, or behavior-changing work. |
| Routing | Module and source path are clear. | Read more source before planning. |
| Confidence | Repository context is verified for limited planning. | Use summaries only to find relevant files. |
| Freshness | No outdated target context. | Run sync or rebuild before relying on context. |
| Missing trust report | trust_report exists and is current. | Run flow release or treat summaries as advisory. |
| 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. |
// 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, confidence report, target source file, and relevant tests. If confidence is weak, inspect the supporting evidence and unresolved follow-up work too.
What should the agent do if a required context file is missing?
Run the relevant import or release flow. If that is not possible, treat summaries as advisory and re-read current source and tests before planning.
// next step
Check context before changing code
Make the agent show its route, trust state, freshness state, evidence, source files, tests, and open repair items before editing.