Synchronize the knowledge graph with the actual codebase.

Refresh Modes

Default to the narrowest scope that can still answer the drift question.

targeted (default during active execution)

• scan only changed modules, touched imports, and directly affected dependency surfaces

• use when a controller already has wave results or graph delta proposals

• ideal after a clean multi-agent wave

full

• scan the whole source tree

• use after refactors, manual edits across many modules, phase completion, or when targeted refresh finds suspicious drift

Process

Step 1: Choose Scope

Decide whether the refresh should be targeted or full .

• If the caller provides changed files, module IDs, or graph delta proposals, start with targeted

• If no reliable scope is available, or the graph may have drifted broadly, use full

• Escalate from targeted to full when the localized scan reveals wider inconsistency

Step 2: Scan the Selected Scope

For each file in scope, extract:

• MODULE_CONTRACT (if present)

• MODULE_MAP (if present)

• imports and exports

• CHANGE_SUMMARY (if present)

In targeted mode, also inspect the immediate dependency surfaces needed to validate CrossLinks accurately.

Step 3: Compare with Knowledge Graph

Read docs/knowledge-graph.xml . Identify:

• Missing modules: files with MODULE_CONTRACT that are not in the graph

• Orphaned modules: graph entries whose files no longer exist in the scanned scope

• Stale CrossLinks: dependencies in the graph that do not match actual imports

• Missing contracts: files that should be governed by GRACE but have no MODULE_CONTRACT

• Escalation signals: evidence that the problem extends beyond the scanned scope

Step 4: Report Drift

Present a structured report:

GRACE Integrity Report

Mode: targeted / full Scope: [modules or files] Synced modules: N Missing from graph: [list files] Orphaned in graph: [list entries] Stale CrossLinks: [list] Files without contracts: [list files] Escalation: no / yes - reason

Step 5: Fix (with user approval)

For each issue, propose a fix:

• Missing from graph - add an entry using the unique ID-based tag convention

• Orphaned - remove or repair the stale graph entry

• Stale links - update CrossLinks from actual imports

• No contracts - generate or restore the missing MODULE_CONTRACT from code analysis and plan context

Ask the user for confirmation before applying fixes.

Step 6: Update Graph

Apply approved fixes to docs/knowledge-graph.xml . Update version only after the selected refresh scope is reconciled.

Rules

• Do not scan the whole repository after every clean wave if a targeted refresh can answer the question

• Prefer controller-supplied graph delta proposals as hints, but validate them against real files

• Escalate to full whenever targeted evidence suggests broader drift