osovv/grace-refresh

Synchronize the GRACE shared artifacts 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.

1. If the caller provides changed files, module IDs, or graph delta proposals, start with targeted
2. If no reliable scope is available, or the graph may have drifted broadly, use full
3. Escalate from targeted to full when the localized scan reveals wider inconsistency

When the optional grace CLI is available, you may use grace lint --path <project-root> as a quick preflight before starting a broader refresh. Treat it as a hint source, not as the refresh itself.

You may also use:

• grace module find <changed-path-or-query> --path <project-root> to resolve the likely module scope from changed files or names
• grace module show M-XXX --path <project-root> --with verification to grab the shared/public contract, dependency, and verification context
• grace file show <path> --path <project-root> --contracts --blocks to inspect file-local/private details without rereading whole source files first

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)
• nearby module-local test files, required log markers, and verification commands when available

Treat shared XML artifacts as public-surface documents:

• shared docs should track module boundaries, dependencies, verification refs, and public module interfaces
• private helpers and implementation-only types may exist in file headers without needing graph or plan entries

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

Step 3: Compare with Shared Artifacts

Read docs/knowledge-graph.xml and, when present, docs/verification-plan.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
• Missing verification entries: governed modules or tests with no corresponding V-M-xxx entry
• Stale verification refs: verification entries whose test files, commands, or required markers no longer match the scoped code
• Escalation signals: evidence that the problem extends beyond the scanned scope

Do not report drift just because a private helper exists in source but not in shared docs. Shared docs should only drift on public contract or dependency changes.

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]
Missing verification entries: [list modules]
Stale verification refs: [list entries]
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
• Missing verification entries - add or repair the matching V-M-xxx block in docs/verification-plan.xml
• Stale verification refs - update test files, commands, or required log markers from the real scoped code

When updating graph or plan artifacts, add only public module-facing annotations and interfaces. Keep private helper details local to the source file.

Ask the user for confirmation before applying fixes.

Step 6: Update Shared Artifacts

Apply approved fixes to docs/knowledge-graph.xml and docs/verification-plan.xml as needed. Update versions 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
• Prefer controller-supplied verification delta proposals as hints, but validate them against real tests and commands
• Escalate to full whenever targeted evidence suggests broader drift