{"record":{"id":"ca2d6542311fd4aa","repo":"Egonex-AI/Understand-Anything","slug":"architecture-update-requires-tour-json-baseline-n","errorCode":null,"errorMessage":"Architecture update requires tour.json; baseline not advanced","messagePattern":"Architecture update requires tour\\.json; baseline not advanced","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/skills/understand/finalize-incremental.mjs","lineNumber":450,"sourceCode":"      scan.importMap ?? {},\n      importMapRefreshPaths,\n    );\n    const nodeIds = new Set(assembled.nodes.map(node => node.id));\n    const pathIndex = buildPathIndex(assembled.nodes);\n    const missingAnalyzedPaths = plan.filesToReanalyze.filter(\n      path => !hasAnalyzedFileCoverage(assembled.nodes, path),\n    );\n    if (missingAnalyzedPaths.length > 0) {\n      throw new Error(\n        `Assembled graph is missing whole-file nodes for analyzed paths: ` +\n        `${missingAnalyzedPaths.join(', ')}; baseline not advanced`,\n      );\n    }\n    if (plan.rerunArchitecture && !existsSync(join(intermediateDir, 'layers.json'))) {\n      throw new Error('Architecture update requires layers.json; baseline not advanced');\n    }\n    if (plan.rerunTour && !existsSync(join(intermediateDir, 'tour.json'))) {\n      throw new Error('Architecture update requires tour.json; baseline not advanced');\n    }\n    const rawLayers = plan.rerunArchitecture\n      ? readJson(join(intermediateDir, 'layers.json'))\n      : previousGraph.layers ?? [];\n    const rawTour = plan.rerunTour\n      ? readJson(join(intermediateDir, 'tour.json'))\n      : previousGraph.tour ?? [];\n    const now = new Date().toISOString();\n    const graph = {\n      ...previousGraph,\n      version: previousGraph.version ?? '1.0.0',\n      project: {\n        ...projectMetadata(previousGraph.project, plan, scan),\n        analyzedAt: now,\n      },\n      nodes: assembled.nodes,\n      edges: assembled.edges,\n      layers: assignLayers(rawLayers, assembled.nodes, assembled.edges),","sourceCodeStart":432,"sourceCodeEnd":468,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/07edf82a04371b6f69779b067bdc8a1a8753a9db/understand-anything-plugin/skills/understand/finalize-incremental.mjs#L432-L468","documentation":"finalize-incremental.mjs finalizes an incremental update by merging intermediate agent artifacts into knowledge-graph.json. When the incremental plan says the tour analysis was re-run (plan.rerunTour), it requires tour.json in the .ua/intermediate/ directory. If that file is absent the update is aborted before the baseline is advanced, so the graph on disk (and its recorded baseline commit) stays consistent and the work is redone on the next run.","triggerScenarios":"Running `node finalize-incremental.mjs <projectRoot>` where incremental-plan.json has action != SKIP and rerunTour == true, but .ua/intermediate/tour.json does not exist when the check at finalize-incremental.mjs:449 executes.","commonSituations":"The tour-builder agent crashed, was skipped, or wrote tour.json to the wrong directory; intermediate artifacts were deleted between the tour step and finalization; a stale incremental-plan.json from an interrupted run requests rerunTour without matching artifacts.","solutions":["Re-run the incremental pipeline so the tour step executes and writes .ua/intermediate/tour.json, then re-run finalize-incremental.mjs.","Regenerate the incremental plan with rerunTour set to false (or run the full /understand pipeline) if tour regeneration is not needed.","Remove the stale .ua/intermediate/incremental-plan.json so the next prepare-incremental.mjs run creates a plan consistent with the artifacts actually produced.","Verify the tour step writes to the resolved data directory (.ua/intermediate/, or .understand-anything/intermediate/ for legacy projects)."],"exampleFix":"// before: finalize with rerunTour: true but no tour.json\nnode finalize-incremental.mjs .   // throws: Architecture update requires tour.json\n\n// after: produce the artifact first\nnode prepare-incremental.mjs .\n# run tour-builder agent (writes .ua/intermediate/tour.json)\nnode finalize-incremental.mjs .","handlingStrategy":"validation","validationCode":"// before running finalize\nimport { existsSync } from 'node:fs';\nimport { join } from 'node:path';\nconst plan = JSON.parse(readFileSync(join(uaDir, 'intermediate', 'incremental-plan.json'), 'utf-8'));\nif (plan.rerunTour && !existsSync(join(uaDir, 'intermediate', 'tour.json'))) {\n  throw new Error('tour.json missing: re-run the tour step before finalizing');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await finalizeIncremental(projectRoot);\n} catch (err) {\n  if (String(err.message).includes('tour.json')) {\n    console.error('Tour artifacts missing; re-run the incremental pipeline.');\n    process.exitCode = 1;\n  } else throw err;\n}","preventionTips":["Run the tour-builder step unconditionally whenever the plan sets rerunTour, in the same pipeline invocation as finalize.","Confirm the agent writes to the resolved data directory (.ua/intermediate/ or legacy .understand-anything/intermediate/), not the repo root.","Discard and regenerate stale incremental-plan.json files after any failed or interrupted run."],"tags":["pipeline","missing-artifact","tour","incremental-analysis"],"backgroundTag":"missing-required-config-field","analyzedSha":"07edf82a04371b6f69779b067bdc8a1a8753a9db","analyzedAt":"2026-09-07T23:20:10.829Z","contentChangedAt":"2026-09-07T23:20:10.829Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}