{"record":{"id":"556fdb40b94ac0f7","repo":"Egonex-AI/Understand-Anything","slug":"architecture-update-requires-layers-json-baseline","errorCode":null,"errorMessage":"Architecture update requires layers.json; baseline not advanced","messagePattern":"Architecture update requires layers\\.json; baseline not advanced","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/skills/understand/finalize-incremental.mjs","lineNumber":447,"sourceCode":"    }\n    const assembled = refreshGraphImports(\n      normalizeAssembled(assembledRaw),\n      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      },","sourceCodeStart":429,"sourceCodeEnd":465,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/07edf82a04371b6f69779b067bdc8a1a8753a9db/understand-anything-plugin/skills/understand/finalize-incremental.mjs#L429-L465","documentation":"finalize-incremental.mjs finalizes an incremental update by merging intermediate agent artifacts into knowledge-graph.json. When the incremental plan says the architecture analysis was re-run (plan.rerunArchitecture), it requires the architecture agent to have written layers.json into the .ua/intermediate/ directory. If that file is absent the update is deliberately aborted before the baseline (fingerprints/meta) is advanced, so the next run will redo the work instead of persisting a graph with stale or missing layers.","triggerScenarios":"Running `node finalize-incremental.mjs <projectRoot>` where the incremental-plan.json in .ua/intermediate/ has action != SKIP and rerunArchitecture == true, but .ua/intermediate/layers.json does not exist (or was deleted) when the check at finalize-incremental.mjs:446 executes.","commonSituations":"The architecture-analyzer agent failed or was skipped but the plan still requested rerunArchitecture; a previous crashed run left a stale plan; intermediate/ artifacts were cleaned (clearIncrementalScratch or manual deletion) between plan creation and finalization; running finalize out of order without completing the architecture step.","solutions":["Re-run the incremental pipeline so the architecture step executes and writes .ua/intermediate/layers.json, then run finalize-incremental.mjs again.","If architecture output is not needed, regenerate the incremental plan with rerunArchitecture set to false (or run the full /understand pipeline) and re-run finalize.","Delete the stale .ua/intermediate/ directory (or incremental-plan.json) so the next prepare-incremental.mjs run builds a fresh, consistent plan.","If layers.json exists but in the wrong location, ensure it is written to the resolved data directory (.ua/intermediate/, or .understand-anything/intermediate/ for legacy projects)."],"exampleFix":"// before: finalizing a plan whose architecture step never ran\nnode finalize-incremental.mjs .   // throws: Architecture update requires layers.json\n\n// after: regenerate intermediate artifacts (incl. layers.json) first\nnode prepare-incremental.mjs .\n# run architecture-analyzer agent (writes .ua/intermediate/layers.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.rerunArchitecture && !existsSync(join(uaDir, 'intermediate', 'layers.json'))) {\n  throw new Error('layers.json missing: re-run the architecture step before finalizing');\n}","typeGuard":null,"tryCatchPattern":"try {\n  await finalizeIncremental(projectRoot);\n} catch (err) {\n  if (String(err.message).includes('layers.json')) {\n    console.error('Architecture artifacts missing; re-run the incremental pipeline.');\n    process.exitCode = 1;\n  } else throw err;\n}","preventionTips":["Always run the full agent sequence (prepare -> analysis agents -> finalize) in one scripted step so rerunArchitecture implies layers.json was just produced.","Never delete or clean .ua/intermediate/ between plan creation and finalization.","Re-create the incremental plan (prepare-incremental.mjs) if any earlier step failed, instead of reusing a stale plan."],"tags":["pipeline","missing-artifact","architecture","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-14T00:17:10.932Z"}