// Blog / maintenance

How to keep agent repo context fresh 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.

technical blog Maintenance workflow after code changes Published May 25, 2026 Updated May 25, 2026

Open GitHub Read audit checklist

// direct answer

Short answer

Keep context fresh by syncing tracked files, rebuilding routing and search indexes, running doctor, updating stale module cards or repair queue items, and treating changed source as stronger than generated summaries until freshness is restored.

Keep repo-local agent context current after commits, merges, and module changes.

// real failure mode

The failure mode

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.

// maintenance model

The repo-local fix

After meaningful commits or merges, run sync and rebuild the compact artifacts 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 card still says the policy path is advisory.

Freshness sync detects the changed files, routing is rebuilt, and the repair queue gets a recheck item.

Until the card is repaired, agents can use it for routing only and must re-read current source.

// repo proof

Repo proof to inspect

Freshness state

`.knowledge/freshness.json`

Freshness records whether tracked context may be stale after source changes.

Use it for

Post-commit checks
Detecting stale knowledge

Do not use it for

Proving runtime behavior

Trust after change

`.knowledge/maintenance/trust_report.json`

Trust buckets should change when knowledge cannot be safely used for planning.

Use it for

Agent caution level
Repair prioritization

Do not use it for

Approving source changes

First-read refresh

`.knowledge/maintenance/routing_bundle.json`

The routing bundle is the first thing new sessions read, so it must reflect current module routes.

Use it for

Session start
Module routing

Do not use it for

Skipping source and tests

Search refresh

`.knowledge/search/index.json`

Search should not point agents toward removed or stale artifacts.

Use it for

Local knowledge search
Finding updated artifacts

Do not use it for

Trusting ranking as correctness

// command transcript

Commands and expected checks

node .knowledge/tools/sync-tracked.js

expected: Tracked files are compared and freshness/trust state is updated.
inspect next: .knowledge/freshness.json and trust_report.json

node .knowledge/tools/build-routing-bundle.js

expected: The route-first artifact is rebuilt after changes.
inspect next: .knowledge/maintenance/routing_bundle.json

node .knowledge/tools/build-search-index.js

expected: Local knowledge search is rebuilt.
inspect next: .knowledge/search/index.json

node .knowledge/tools/doctor.js

expected: The knowledge layer readiness is checked.
inspect next: .knowledge/maintenance/quality_report.json

Freshness lifecycle repo-local proof

How context becomes current again

01 Commit or merge changes source, tests, docs, or module boundaries.

02 Sync checks tracked files and marks stale or suspect context.

03 Routing and search are rebuilt for the next agent session.

04 Repair queue captures knowledge debt that still needs human or agent work.

05 Source and tests stay authoritative until repaired knowledge catches up.

// field guide

Post-change maintenance

Not every change needs the same maintenance depth.
Change type	Minimum action	Extra action
Docs-only copy edit	Build search if knowledge docs changed.	No module repair unless behavior claims changed.
Source file changed	Run sync and rebuild routing.	Recheck module card if summary mentions that path.
Tests changed	Run sync and note changed evidence.	Update evidence if test expectations changed.
Merge across modules	Run full doctor and routing rebuild.	Review repair queue and Inspector.

// guardrails

What the agent should not trust blindly

Freshness is not correctness. It only tells the agent whether context may be stale.
When source changed, generated summaries become weaker until rechecked.
Keep maintenance commands boring and repeatable so agents can run them safely.

// common mistakes

Common mistakes

Updating docs but not rebuilding search.
Letting a stale module card stay trusted after source changes.
Treating doctor score as proof that code works.

// 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.

// page-specific next step

Use this page after merges or module changes

Run sync, rebuild routing and search, run doctor, and make unresolved context debt visible before the next agent session.

Read handoff article Open GitHub View Inspector