Skip to content

Graphs that teach > graphs that impress. Turn any code into an interactive knowledge graph you can explore, search, and ask questions about. Works with Claude Code, Codex, Cursor, Copilot, Gemini CLI, and more.

docs(analysis): require symbol preservation and targeted repair

Lum11042a3fee478c75
diff --git a/tests/skill/understand/test_incremental_skill_contract.test.mjs b/tests/skill/understand/test_incremental_skill_contract.test.mjs
index f9eba88b..8ef13b02 100644
--- a/tests/skill/understand/test_incremental_skill_contract.test.mjs
+++ b/tests/skill/understand/test_incremental_skill_contract.test.mjs
@@ -12,6 +12,9 @@ const hook = readFileSync(
resolve(__dirname, '../../../understand-anything-plugin/hooks/auto-update-prompt.md'),
'utf-8',
);
+const analyzer = readFileSync(
+ resolve(__dirname, '../../../understand-anything-plugin/agents/file-analyzer.md'), 'utf-8',
+);
describe('incremental execution contract', () => {
it.each([skill, hook])('routes inventory and baseline updates through bundled helpers', content => {
@@ -38,4 +41,22 @@ describe('incremental execution contract', () => {
expect(skill).toContain('With explicit `--review`');
expect(skill).toContain('jump to the `--review` graph-reviewer path in Phase 6');
});
+
+ it.each([skill, hook])('requires deterministic symbol checking and one targeted repair', content => {
+ expect(content).toContain('incremental-symbol-baseline.json');
+ expect(content).toContain('validate-incremental-symbols.mjs');
+ expect(content).toContain('incremental-symbol-report.json');
+ expect(content).toContain('prepare-symbol-retry.mjs');
+ expect(content).toContain('incremental-symbol-retry.json');
+ expect(content).toContain('previousSymbols');
+ expect(content).toContain('missingSymbols');
+ expect(content).toContain('independently reruns the shared symbol');
+ });
+
+ it('keeps significance filtering for new symbols but requires accounting for old methods', () => {
+ expect(analyzer).toContain('New symbols continue to use the filter above');
+ expect(analyzer).toContain('classes[].methods');
+ expect(analyzer).toContain('check the complete `previousSymbols` checklist');
+ expect(analyzer).toContain('explicitly report an error with its ID/name');
+ });
});
diff --git a/understand-anything-plugin/agents/file-analyzer.md b/understand-anything-plugin/agents/file-analyzer.md
index df701a0a..846bdb32 100644
--- a/understand-anything-plugin/agents/file-analyzer.md
+++ b/understand-anything-plugin/agents/file-analyzer.md
@@ -246,6 +246,10 @@ For significant functions and classes from the script output (code files only),
Skip trivial one-liners, type aliases, simple re-exports, and auto-generated boilerplate.
+**Incremental preservation overrides significance filtering for existing symbols.** If the prompt provides `previousSymbols`, reconcile every listed function, class, and method against current source, including methods in `classes[].methods` rather than just top-level `functions`. A symbol already in the graph that still exists MUST be emitted even if it has become short, private, or otherwise falls below the significance thresholds. New symbols continue to use the filter above. Match by file, kind, owning class, and name; use line ranges only to locate code within that revision. Preserve canonical IDs where the symbol identity is unchanged.
+
+Before writing output, check the complete `previousSymbols` checklist for every file. Emit all surviving symbols with newly derived summaries, tags, complexity, and edges. For confirmed deletions, omit the nodes and report the deleted IDs. If a checklist item cannot be accounted for (ambiguous ownership, unsupported syntax, parse failure, or incomplete source), explicitly report an error with its ID/name; do not claim successful completion or silently drop it. A `missingSymbols` repair prompt requires a complete replacement analysis of the affected files, including their other nodes and edges. Never copy the old semantic nodes/edges back merely to pass validation.
+
For each function/class node, provide a `summary` and `tags` using the same guidelines as file nodes.
### Step 3 -- Create Edges
diff --git a/understand-anything-plugin/hooks/auto-update-prompt.md b/understand-anything-plugin/hooks/auto-update-prompt.md
index aae89f73..48bfc106 100644
--- a/understand-anything-plugin/hooks/auto-update-prompt.md
+++ b/understand-anything-plugin/hooks/auto-update-prompt.md
@@ -51,7 +51,7 @@ Read `filesToReanalyze` from the plan. It never contains deleted, ignored, cosme
--changed-files="$UA_DIR/intermediate/changed-files.json"
```
- Dispatch file-analyzer for those batches only, using `agents/file-analyzer.md` and the batch prompt contract from the `/understand` skill. Preserve each original batch index in its output filename. Retry a failed dispatch once; if it still fails, **STOP** without running the finalizer or advancing the baseline.
+ Dispatch file-analyzer for those batches only, using `agents/file-analyzer.md` and the batch prompt contract from the `/understand` skill. Include `previousSymbols` for each batch's files from `incremental-symbol-baseline.json`: old symbol IDs, names, types, paths, line ranges, and class containment. Existing symbols that still exist must survive significance filtering. Preserve each original batch index in its output filename. Retry a failed dispatch once; if it still fails, **STOP** without running the finalizer or advancing the baseline.
## Phase 2 — Merge
@@ -61,7 +61,19 @@ Run the deterministic merge in both empty and non-empty analyzer cases:
python "$PLUGIN_ROOT/skills/understand/merge-batch-graphs.py" "$PROJECT_ROOT"
```
-It combines `batch-existing.json` with fresh batches and recovers imports from the refreshed `scan-result.json`, including `config:`, `schema:`, `service:`, and other valid whole-file nodes. Require `$UA_DIR/intermediate/assembled-graph.json`; on failure, report it and **STOP** without advancing fingerprints or meta.
+It combines `batch-existing.json` with fresh batches and recovers imports from the refreshed `scan-result.json`, including `config:`, `schema:`, `service:`, and other valid whole-file nodes. Require both a successful exit and `$UA_DIR/intermediate/assembled-graph.json`; failed candidates remain on disk for diagnosis.
+
+Merge runs `validate-incremental-symbols.mjs`, comparing the preserved old symbols with the candidate and base/current source. Read `incremental-symbol-report.json` for per-file counts, missing IDs/names, and still-present/deleted/unknown classifications. A same-size node set can still have missing symbols. Confirmed deletions are allowed; still-present or unknown omissions block publication.
+
+If the report has `unresolvedFiles`, prepare one targeted symbol retry:
+
+```bash
+node "$PLUGIN_ROOT/skills/understand/prepare-symbol-retry.mjs" "$PROJECT_ROOT"
+```
+
+Dispatch only `batches[]` from `incremental-symbol-retry.json`, with the usual file-analyzer prompt and its supplied `files`, `batchIndex`, `batchImportData`, `neighborMap`, `previousSymbols`, and `missingSymbols`. Reanalyze those files completely. The helper preserves other merged results in `batch-0.json`, removes affected contributions and incident edges, and clears old numeric shards before repair. Rerun merge after this one repair. Never paste old nodes or semantic edges back into the candidate. The attempt is recorded for the base/head commits, even across repeated prepare calls.
+
+If the helper, repair dispatch, or second merge fails, **STOP** with diagnostics and leave `knowledge-graph.json`, `fingerprints.json`, and `meta.json` unchanged. Other merge failures without eligible unresolved files also stop immediately.
Do not dispatch assemble-reviewer or graph-reviewer for automatic updates.
@@ -80,7 +92,7 @@ Run:
node "$PLUGIN_ROOT/skills/understand/finalize-incremental.mjs" "$PROJECT_ROOT"
```
-The finalizer performs deterministic graph/layer/tour validation, atomically saves `knowledge-graph.json`, patches changed fingerprints while preserving untouched entries, removes deleted fingerprints, and only then writes `meta.json`. A graph-save failure must never advance the fingerprint or commit baseline.
+The finalizer performs deterministic graph/layer/tour validation and independently reruns the shared symbol check on the exact graph before writing. It atomically saves `knowledge-graph.json`, patches changed fingerprints while preserving untouched entries, removes deleted fingerprints, and only then writes `meta.json`. A graph-save failure must never advance the fingerprint or commit baseline. If symbol loss is first detected here, follow the same one-retry procedure, rerun merge and any required architecture/tour phases, then finalize; an already-used or unsuccessful repair must stop with the old graph and baselines intact.
Report:
diff --git a/understand-anything-plugin/skills/understand/SKILL.md b/understand-anything-plugin/skills/understand/SKILL.md
index 319f6638..f496f910 100644
--- a/understand-anything-plugin/skills/understand/SKILL.md
+++ b/understand-anything-plugin/skills/understand/SKILL.md
@@ -212,6 +212,7 @@ Determine whether to run a full analysis or incremental update.
- `$UA_DIR/intermediate/scan-result.json`
- `$UA_DIR/intermediate/changed-files.json`
- `$UA_DIR/intermediate/batch-existing.json` for partial/architecture updates
+ - `$UA_DIR/intermediate/incremental-symbol-baseline.json`, the previous node inventory for reanalyzed files, bound to the base/head commits
Read `incremental-plan.json` and store its `action`, `filesToReanalyze`, `deletedFiles`, `rerunArchitecture`, and `rerunTour` values. Follow this gate:
@@ -399,7 +400,7 @@ Include the script's warnings in `$PHASE_WARNINGS` for the reviewer.
`prepare-incremental.mjs` has already refreshed the complete file inventory and `importMap`, written the exact analyzer list, and pruned changed/deleted paths from the old graph into `batch-existing.json`.
-1. If `filesToReanalyze` is non-empty, dispatch file-analyzer only for the batches from the incremental `batches.json`, using the same prompt template as the full path. Never add `deletedFiles`, `cosmeticFiles`, `ignoredFiles`, or `generatedArtifactFiles` to a prompt.
+1. If `filesToReanalyze` is non-empty, dispatch file-analyzer only for the batches from the incremental `batches.json`, using the same prompt template as the full path. Include `previousSymbols`: the function/class/method node checklist for those files from `incremental-symbol-baseline.json` (IDs, names, types, paths, line ranges, and class containment). Existing symbols that still exist must survive significance filtering; regenerate their semantics from current source. Never add `deletedFiles`, `cosmeticFiles`, `ignoredFiles`, or `generatedArtifactFiles` to a prompt.
2. If `filesToReanalyze` is empty, dispatch no agent and create no new batch file.
3. Run the merge script in both cases:
@@ -407,7 +408,19 @@ Include the script's warnings in `$PHASE_WARNINGS` for the reviewer.
python "<SKILL_DIR>/merge-batch-graphs.py" "$PROJECT_ROOT"
```
-The merge combines `batch-existing.json` with any fresh batch output. Its import recovery reads the already-refreshed `scan-result.json`, so added and removed imports are reflected during this same run. Verify `assembled-graph.json` exists before continuing.
+The merge combines `batch-existing.json` with any fresh batch output. Its import recovery reads the already-refreshed `scan-result.json`, so added and removed imports are reflected during this same run. Require a successful exit as well as `assembled-graph.json` before continuing. A failed merge can deliberately leave an incomplete candidate for diagnosis.
+
+**Symbol-loss gate and one targeted retry:** Merge invokes `validate-incremental-symbols.mjs`. Read `incremental-symbol-report.json`: it reports per-file before/after counts and missing node IDs/names even when counts stay equal. Missing functions, classes, and methods (including `classes[].methods`) are classified against base/current source with the same strict parser. Only confirmed source deletions are allowed; still-present and unknown symbols block publication.
+
+When the report has `unresolvedFiles`, prepare exactly one repair:
+
+```bash
+node "<SKILL_DIR>/prepare-symbol-retry.mjs" "$PROJECT_ROOT"
+```
+
+This helper revalidates the candidate, records attempt 1/1 for the base/head commits, removes the affected files' new contributions and their incident edges, clears old numeric batch shards, and preserves other merged results in `batch-0.json`. Dispatch only `batches[]` from `incremental-symbol-retry.json`, using each batch's `files`, `batchIndex`, `batchImportData`, `neighborMap`, `previousSymbols`, and `missingSymbols`. Use the normal file-analyzer prompt and output names. The repair must reanalyze each affected file completely, not just append missing nodes. Then rerun merge. Do not rerun prepare to obtain another retry; the attempt remains used for those commits.
+
+If repair preparation, the repair dispatch, or the second merge fails, **STOP** and retain diagnostics. Do not publish or advance `knowledge-graph.json`, `fingerprints.json`, or `meta.json`. Never concatenate old nodes or old semantic edges into the candidate to satisfy the gate. Other merge failures without eligible unresolved files stop immediately. On success, continue to the applicable architecture/tour phases.
---
@@ -606,7 +619,7 @@ After the applicable Phase 4/5 work is complete, finalize either incremental act
node "<SKILL_DIR>/finalize-incremental.mjs" "$PROJECT_ROOT"
```
-This helper validates/deduplicates nodes and edges, reconciles layers/tour, atomically saves the graph, patches only changed fingerprints while preserving all others, removes deleted fingerprints, and only then advances `meta.json`.
+This helper validates/deduplicates nodes and edges, reconciles layers/tour, and independently reruns the shared symbol validator on the exact graph to be saved. It then atomically saves the graph, patches only changed fingerprints while preserving all others, removes deleted fingerprints, and only then advances `meta.json`. A cached successful merge report cannot bypass the save check. If symbol loss is first detected here, use the same one-retry procedure above, rerun merge and any required architecture/tour phases, then finalize again; if the retry was already used or remains unresolved, **STOP** with the old graph and baselines intact.
- Without `--review`, report the incremental summary and **STOP**. Do not run Phase 6 or the full-save Phase 7; this is what prevents the ordinary local update from paying for whole-graph review.
- With `--review`, copy the newly saved `$UA_DIR/knowledge-graph.json` to `$UA_DIR/intermediate/assembled-graph.json`, then continue to the full graph-reviewer path in Phase 6. Do not run the inline default reviewer.