// Blog / maintenance
How to keep coding-agent repository context current after commits and merges
Agent context goes stale the same way docs go stale: code changes first, and the summaries only catch up if maintenance is explicit.
// direct answer
Short answer
Keep context current by syncing tracked files, rebuilding routing and search indexes, running the .knowledge health check, updating outdated module summaries or follow-up items, and treating changed source as stronger than generated summaries until the context is refreshed.
Keep repo-local agent context current after commits, merges, and module changes.
// the problem
Repository context falls behind the code
A merge changes source files, tests, or module boundaries, but the agent context still describes the pre-merge world.
The next agent reads a plausible summary and plans against old behavior.
Freshness needs to be tracked as a maintenance signal, not remembered as a vibe.
// keeping context current
Refresh repository context after meaningful changes
After meaningful commits or merges, run sync and rebuild the compact files agents read first.
If source changed under a module summary, mark or repair the knowledge rather than pretending it is still current.
Use doctor output as the readiness signal for the knowledge layer, not for product correctness.
// concrete example
A merge that touches policy files
A merge modifies policy enforcement and tests. The old module summary still describes the previous policy path.
The freshness check detects the changed files, routing is rebuilt, and the follow-up list gets a recheck item.
Until the card is repaired, agents can use it for routing only and must re-read current source.
// files you can inspect
Files that show whether context is current
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/freshness.json
Freshness records whether tracked context may be stale after source changes.
- Post-commit checks
- Detecting stale knowledge
- Proving runtime behavior
.knowledge/maintenance/trust_report.json
Confidence levels should change when repository context cannot safely support planning.
- Agent caution level
- Repair prioritization
- Approving source changes
.knowledge/maintenance/routing_bundle.json
The routing bundle is the first thing new sessions read, so it must reflect current module routes.
- Session start
- Module routing
- Skipping source and tests
.knowledge/search/index.json
Search should not point agents toward removed or outdated files.
- Local knowledge search
- Finding updated files
- Trusting ranking as correctness
.knowledge/tools/install-git-hooks.js
Git hooks can refresh knowledge after commit, merge, or checkout when a team wants that workflow.
- Optional local automation
- Post-change hygiene
- Mandatory CI enforcement
.knowledge/github-action-templates/
knowledge-health.yml, knowledge-pr-summary.yml, and knowledge-evaluation.yml turn freshness checks into repeatable CI workflows.
- CI health checks
- PR summaries
- Evaluation gates
- Replacing human repair decisions
// commands to try
Commands and expected checks
node .knowledge/tools/sync-tracked.js - what it does
- Tracked files are compared and freshness/trust state is updated.
- where to look
- .knowledge/freshness.json and trust_report.json
node .knowledge/tools/install-git-hooks.js - what it does
- Optional git hooks are installed to refresh knowledge around commit, merge, or checkout workflows.
- where to look
- .git/hooks/ and .knowledge/maintenance/events/
node .knowledge/tools/build-routing-bundle.js - what it does
- The task map is rebuilt after changes.
- where to look
- .knowledge/maintenance/routing_bundle.json
node .knowledge/tools/build-search-index.js - what it does
- Local knowledge search is rebuilt.
- where to look
- .knowledge/search/index.json
node .knowledge/tools/doctor.js - what it does
- The knowledge layer readiness is checked.
- where to look
- .knowledge/maintenance/quality_report.json
How repository context gets updated
// practical reference
Post-change maintenance
| Change type | Minimum action | Extra action |
|---|---|---|
| Docs-only copy edit | Build search if knowledge docs changed. | No module repair unless behavior claims changed. |
| Small copy edit | Do not run full maintenance by default. | Rebuild search only if knowledge docs changed. |
| Source file changed | Run sync and rebuild routing. | Recheck the module summary if it mentions that path. |
| Tests changed | Run sync and note changed evidence. | Update evidence if test expectations changed. |
| CI setup | Copy knowledge-health.yml, knowledge-pr-summary.yml, or knowledge-evaluation.yml. | Keep human repair review for stale context. |
| Merge across modules | Run the full .knowledge health check and rebuild routing. | Review follow-up work and Inspector. |
// quick FAQ
FAQ
Should freshness maintenance run in CI?
It can. The useful pattern is to run health and PR summaries in CI while still letting humans decide how to repair stale context.
What if a module remains low-confidence?
That is acceptable if agents treat it as route-only context and re-read source before behavior claims.
What if freshness.json is missing in a fresh archive?
Run flow import first. Freshness data is created inside your repository so it can reflect that project’s tracked files.
// next step
Keep context current after commits and merges
Run sync, rebuild routing and search, run the .knowledge health check, and make unresolved context visible before the next agent session.