grace-refresh
Synchronize GRACE shared artifacts with the actual codebase. Use targeted refresh after controlled waves, or full refresh after refactors and when you suspect wider drift between the graph, verification plan, and code.
git clone --depth 1 https://github.com/osovv/grace-marketplace /tmp/grace-refresh && cp -r /tmp/grace-refresh/skills/grace/grace-refresh ~/.claude/skills/grace-refreshSKILL.md
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: ```text 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
Answer a question about a GRACE project using full project context. Use when the user has a question about the codebase, architecture, modules, or implementation — loads all GRACE artifacts, navigates the knowledge graph, and provides a grounded answer with citations.
Operate the optional `grace` CLI against a GRACE project. Use when you want to lint GRACE artifacts, explain/remediate lint issues, check autonomy readiness, inspect project or module health, inspect verification entries, resolve modules from names or file paths, inspect shared/public module context, or inspect file-local/private markup through `grace lint`, `grace status`, `grace module`, `grace verification`, and `grace file show`.
Execute the full GRACE development plan step by step with controller-managed context packets, verification-plan excerpts, scoped reviews, level-based verification, and commits after validated sequential steps.
Complete GRACE methodology reference. Use when explaining GRACE to users, onboarding new projects, or when you need to understand the GRACE framework - its principles, semantic markup, knowledge graphs, contracts, testing, and unique tag conventions.
Debug an issue using GRACE semantic navigation. Use when encountering bugs, errors, or unexpected behavior - navigate through the graph, verification plan, and semantic blocks to analyze the mismatch and apply a targeted fix.
Bootstrap GRACE framework structure for a new project. Use when starting a new project with GRACE methodology - creates docs/ directory, AGENTS.md, and XML templates for requirements, technology, development plan, verification plan, knowledge graph, and operational packet contracts.
Execute a GRACE development plan in controller-managed parallel waves with selectable safety profiles, verification-plan excerpts, batched shared-artifact sync, and scoped reviews.
Run the GRACE architectural planning phase. Use when you have requirements and technology decisions defined and need to design the module architecture, create contracts, map data flows, and establish verification references. Produces development-plan.xml, verification-plan.xml, and knowledge-graph.xml.