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.

fix(lessons): normalize the tour with the finalizer's resolver before dispatching lessons (#753)

06FallingLight90bcb8ae9d45fa
diff --git a/understand-anything-plugin/hooks/auto-update-prompt.md b/understand-anything-plugin/hooks/auto-update-prompt.md
index 5a4707b3..13cb9add 100644
--- a/understand-anything-plugin/hooks/auto-update-prompt.md
+++ b/understand-anything-plugin/hooks/auto-update-prompt.md
@@ -88,7 +88,7 @@ Do not dispatch assemble-reviewer or graph-reviewer for automatic updates.
## Phase 3 — Conditional architecture and tour
- For `PARTIAL_UPDATE`, dispatch neither agent. The finalizer preserves existing layer assignments and tour prose, removes dangling references/empty layers, and assigns new nodes deterministically by directory depth, graph connectivity, then prior layer order.
-- For `ARCHITECTURE_UPDATE`, dispatch architecture-analyzer on the full merged node/edge set, including previous layers for naming stability, and write `$UA_DIR/intermediate/layers.json`. Then dispatch tour-builder and write `$UA_DIR/intermediate/tour.json`. Before dispatching the lesson writer, delete any stale `$UA_DIR/intermediate/code-lessons.json` and `$UA_DIR/intermediate/code-lessons.normalized.json` left by an interrupted earlier run (never touch the served `$UA_DIR/code-lessons.json`). Then dispatch `code-lesson-writer` (same dispatch shape as SKILL.md §Code Lessons: rebuilt tour, node summaries, language directive) and write `$UA_DIR/intermediate/code-lessons.json`, normalized into `$UA_DIR/intermediate/code-lessons.normalized.json` per the SKILL.md Phase 5 rules. Append `$LANGUAGE_DIRECTIVE` to the dispatch prompt when Phase 0 resolved one — without it, a project stored with a non-English `outputLanguage` would get its lessons regenerated in English beside the non-English graph and tour. Lessons are best-effort here: retry the dispatch once, and if it still fails leave no staged document, record the warning, and continue — publication (Phase 4) then removes the stale served sidecar instead of leaving lessons for the previous tour.
+- For `ARCHITECTURE_UPDATE`, dispatch architecture-analyzer on the full merged node/edge set, including previous layers for naming stability, and write `$UA_DIR/intermediate/layers.json`. Then dispatch tour-builder and write `$UA_DIR/intermediate/tour.json`. Then normalize the tour deterministically — run `node "$PLUGIN_ROOT/skills/understand/normalize-tour.mjs" "$PROJECT_ROOT"` and use the resulting `$UA_DIR/intermediate/tour.normalized.json` for the lesson dispatch (the finalizer applies the same normalization at save time; hand-written conversion disagrees with it). Before dispatching the lesson writer, delete any stale `$UA_DIR/intermediate/code-lessons.json` and `$UA_DIR/intermediate/code-lessons.normalized.json` left by an interrupted earlier run (never touch the served `$UA_DIR/code-lessons.json`). Then dispatch `code-lesson-writer` (same dispatch shape as SKILL.md §Code Lessons: rebuilt tour, node summaries, language directive) and write `$UA_DIR/intermediate/code-lessons.json`, normalized into `$UA_DIR/intermediate/code-lessons.normalized.json` per the SKILL.md Phase 5 rules. Append `$LANGUAGE_DIRECTIVE` to the dispatch prompt when Phase 0 resolved one — without it, a project stored with a non-English `outputLanguage` would get its lessons regenerated in English beside the non-English graph and tour. Lessons are best-effort here: retry the dispatch once, and if it still fails leave no staged document, record the warning, and continue — publication (Phase 4) then removes the stale served sidecar instead of leaving lessons for the previous tour.
Retry either required agent once. If it still fails, **STOP** without advancing the baseline.
diff --git a/understand-anything-plugin/skills/understand/SKILL.md b/understand-anything-plugin/skills/understand/SKILL.md
index 4636f348..315c30ea 100644
--- a/understand-anything-plugin/skills/understand/SKILL.md
+++ b/understand-anything-plugin/skills/understand/SKILL.md
@@ -596,13 +596,13 @@ Pass these parameters in the dispatch prompt:
> [list of ALL edges — include all edge types for complete graph topology analysis]
> ```
-After the subagent completes, read `$UA_DIR/intermediate/tour.json` and normalize it into a final `tour` array. Apply these steps **in order**:
+After the subagent completes, normalize the tour **deterministically** — do NOT apply the normalization by hand. Hand-written conversion (`file:<relative-path>` for every raw path) disagrees with the resolver the finalizer uses at save time (a raw `README.md` reference must resolve to `document:README.md`, not become a dangling `file:README.md`), which would leave lesson `tourOrder` anchors describing a tour that was never saved. Instead run:
-1. **Unwrap envelope:** If the file contains `{ "steps": [...] }` instead of a plain array, extract the inner array. (The prompt requests a plain array, but LLMs may still produce an envelope.)
-2. **Rename legacy fields:** If any step has `nodesToInspect` instead of `nodeIds`, rename it → `nodeIds`. If any step has `whyItMatters` instead of `description`, rename it → `description`.
-3. **Convert file paths:** If `nodeIds` entries are raw file paths without a known prefix (`file:`, `config:`, `document:`, `service:`, `pipeline:`, `table:`, `schema:`, `resource:`, `endpoint:`), convert them to `file:<relative-path>`.
-4. **Drop dangling refs:** Remove any `nodeIds` entries that do not exist in the merged node set.
-5. **Sort** by `order` before saving.
+```bash
+node "<SKILL_DIR>/normalize-tour.mjs" "$PROJECT_ROOT"
+```
+
+The helper reads `$UA_DIR/intermediate/assembled-graph.json` and `$UA_DIR/intermediate/tour.json`, applies the finalizer's exact normalization (envelope unwrap, legacy-field rename, pathIndex-based reference resolution, dangling-ref removal, sort by `order`), and writes `$UA_DIR/intermediate/tour.normalized.json`. Use that file's content as the final `tour` array for every downstream step in this run — the Code Lessons dispatch below, graph assembly, and Phase 7 all reference `tour.normalized.json`, never the raw `tour.json`.
Each element of the final `tour` array MUST have this shape:
@@ -633,7 +633,7 @@ Report to the user: `[Phase 5/7] Writing code lessons...`
0. **Clear stale lesson scratch files.** An interrupted earlier run can leave `$UA_DIR/intermediate/code-lessons.json` (raw) and `$UA_DIR/intermediate/code-lessons.normalized.json` (staged) behind — full-run initialization only creates the intermediate directory. Delete both files before every lesson attempt, or the next writer's missing output could let those stale scratch files be normalized and published as if they belonged to this run. Never touch the served `$UA_DIR/code-lessons.json` here.
-1. **Resolve tour-covered files.** For each normalized tour step, resolve every `nodeIds` entry to its file-level node and collect the node's `filePath`. Record for each covered file the smallest referencing step `order` as its primary tour anchor.
+1. **Resolve tour-covered files.** Read the normalized tour from `$UA_DIR/intermediate/tour.normalized.json` (written by the deterministic tour normalization above). For each normalized tour step, resolve every `nodeIds` entry to its file-level node and collect the node's `filePath`. Record for each covered file the smallest referencing step `order` as its primary tour anchor.
2. **Dispatch a subagent** using the `code-lesson-writer` agent definition (at `agents/code-lesson-writer.md`). Pass these parameters in the dispatch prompt:
@@ -641,9 +641,9 @@ Report to the user: `[Phase 5/7] Writing code lessons...`
> Project root: `$PROJECT_ROOT`
> Write output to: `$UA_DIR/intermediate/code-lessons.json`
>
-> Tour steps:
+> Tour steps (from `$UA_DIR/intermediate/tour.normalized.json`):
> ```json
-> [<the normalized tour array>]
+> [<the normalized tour array from tour.normalized.json>]
> ```
>
> Detailed files (read source from disk; produce overview + sections):
@@ -713,7 +713,7 @@ Assemble the full KnowledgeGraph JSON object:
"nodes": [<all nodes from assembled-graph.json after Phase 3 review>],
"edges": [<all edges from assembled-graph.json after Phase 3 review>],
"layers": [<layers from Phase 4>],
- "tour": [<steps from Phase 5>]
+ "tour": [<steps from `$UA_DIR/intermediate/tour.normalized.json` (Phase 5)>]
}
```
diff --git a/understand-anything-plugin/skills/understand/finalize-incremental.mjs b/understand-anything-plugin/skills/understand/finalize-incremental.mjs
index d02de8d9..f32d453f 100644
--- a/understand-anything-plugin/skills/understand/finalize-incremental.mjs
+++ b/understand-anything-plugin/skills/understand/finalize-incremental.mjs
@@ -505,8 +505,10 @@ if (isCliEntry()) {
export {
assignLayers,
+ buildPathIndex,
commonParentDepth,
hasAnalyzedFileCoverage,
+ normalizeAssembled,
normalizeTour,
refreshGraphImports,
};
diff --git a/understand-anything-plugin/skills/understand/normalize-tour.mjs b/understand-anything-plugin/skills/understand/normalize-tour.mjs
new file mode 100644
index 00000000..2f99c5cd
--- /dev/null
+++ b/understand-anything-plugin/skills/understand/normalize-tour.mjs
@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/**
+ * Normalize the freshly built tour with the exact resolver the incremental
+ * finalizer will apply at save time, so downstream steps (lesson dispatch in
+ * particular) work against the tour that will actually be saved. A raw
+ * "README.md" reference resolves to document:README.md here, not to a
+ * dangling file:README.md produced by the hand-written conversion rule this
+ * replaces.
+ *
+ * Usage: node normalize-tour.mjs <projectRoot>
+ *
+ * Reads $UA_DIR/intermediate/assembled-graph.json (nodes, resolved like the finalizer)
+ * $UA_DIR/intermediate/tour.json (raw tour-builder output)
+ * Writes $UA_DIR/intermediate/tour.normalized.json (atomically)
+ *
+ * Deterministic: same inputs plus the finalizer's normalizeTour always yield
+ * the document the finalizer will embed in knowledge-graph.json.
+ */
+
+import { createRequire } from 'node:module';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { existsSync, readFileSync, realpathSync, renameSync, writeFileSync } from 'node:fs';
+import { buildPathIndex, normalizeAssembled, normalizeTour } from './finalize-incremental.mjs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const pluginRoot = resolve(__dirname, '../..');
+const require = createRequire(resolve(pluginRoot, 'package.json'));
+
+let core;
+try {
+ core = await import(pathToFileURL(require.resolve('@understand-anything/core')).href);
+} catch {
+ core = await import(pathToFileURL(resolve(pluginRoot, 'packages/core/dist/index.js')).href);
+}
+
+const { resolveUaDir } = core;
+
+function readJson(path) {
+ return JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+function atomicWriteJson(path, value) {
+ const tempPath = `${path}.tmp-${process.pid}-${Date.now()}`;
+ writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf-8');
+ renameSync(tempPath, path);
+ // Verify the durable target, not the temporary file.
+ JSON.parse(readFileSync(path, 'utf-8'));
+}
+
+const args = process.argv.slice(2);
+if (args.length !== 1 || args[0].startsWith('--')) {
+ console.error('Usage: node normalize-tour.mjs <projectRoot>');
+ process.exit(1);
+}
+
+const projectRoot = realpathSync(args[0]);
+const uaDir = resolveUaDir(projectRoot);
+const intermediateDir = join(uaDir, 'intermediate');
+const graphPath = join(intermediateDir, 'assembled-graph.json');
+const tourPath = join(intermediateDir, 'tour.json');
+
+if (!existsSync(graphPath)) {
+ console.error('normalize-tour.mjs failed: intermediate/assembled-graph.json is missing; run the merge phase first');
+ process.exit(1);
+}
+if (!existsSync(tourPath)) {
+ console.error('normalize-tour.mjs failed: intermediate/tour.json is missing; run tour-builder first');
+ process.exit(1);
+}
+
+// Mirror the finalizer exactly: the same node normalization feeds the same
+// pathIndex, so resolveNodeRef agrees on every reference at save time.
+const assembled = normalizeAssembled(readJson(graphPath));
+if (assembled.nodes.length === 0) {
+ console.error('normalize-tour.mjs failed: assembled-graph.json has no usable nodes');
+ process.exit(1);
+}
+const nodeIds = new Set(assembled.nodes.map(node => node.id));
+const normalized = normalizeTour(readJson(tourPath), nodeIds, buildPathIndex(assembled.nodes));
+
+atomicWriteJson(join(intermediateDir, 'tour.normalized.json'), normalized);
+process.stdout.write(`Tour normalized: ${normalized.length} step(s) -> tour.normalized.json\n`);