Architecture update requires layers.json; baseline not advan

Error message

Architecture update requires layers.json; baseline not advanced

What it means

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.

Source

Thrown at understand-anything-plugin/skills/understand/finalize-incremental.mjs:447

    }
    const assembled = refreshGraphImports(
      normalizeAssembled(assembledRaw),
      scan.importMap ?? {},
      importMapRefreshPaths,
    );
    const nodeIds = new Set(assembled.nodes.map(node => node.id));
    const pathIndex = buildPathIndex(assembled.nodes);
    const missingAnalyzedPaths = plan.filesToReanalyze.filter(
      path => !hasAnalyzedFileCoverage(assembled.nodes, path),
    );
    if (missingAnalyzedPaths.length > 0) {
      throw new Error(
        `Assembled graph is missing whole-file nodes for analyzed paths: ` +
        `${missingAnalyzedPaths.join(', ')}; baseline not advanced`,
      );
    }
    if (plan.rerunArchitecture && !existsSync(join(intermediateDir, 'layers.json'))) {
      throw new Error('Architecture update requires layers.json; baseline not advanced');
    }
    if (plan.rerunTour && !existsSync(join(intermediateDir, 'tour.json'))) {
      throw new Error('Architecture update requires tour.json; baseline not advanced');
    }
    const rawLayers = plan.rerunArchitecture
      ? readJson(join(intermediateDir, 'layers.json'))
      : previousGraph.layers ?? [];
    const rawTour = plan.rerunTour
      ? readJson(join(intermediateDir, 'tour.json'))
      : previousGraph.tour ?? [];
    const now = new Date().toISOString();
    const graph = {
      ...previousGraph,
      version: previousGraph.version ?? '1.0.0',
      project: {
        ...projectMetadata(previousGraph.project, plan, scan),
        analyzedAt: now,
      },

View on GitHub (pinned to 07edf82a04)

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).

Example fix

// before: finalizing a plan whose architecture step never ran
node finalize-incremental.mjs .   // throws: Architecture update requires layers.json

// after: regenerate intermediate artifacts (incl. layers.json) first
node prepare-incremental.mjs .
# run architecture-analyzer agent (writes .ua/intermediate/layers.json)
node finalize-incremental.mjs .

Defensive patterns

Strategy: validation

Validate before calling

// before running finalize
import { existsSync } from 'node:fs';
import { join } from 'node:path';
const plan = JSON.parse(readFileSync(join(uaDir, 'intermediate', 'incremental-plan.json'), 'utf-8'));
if (plan.rerunArchitecture && !existsSync(join(uaDir, 'intermediate', 'layers.json'))) {
  throw new Error('layers.json missing: re-run the architecture step before finalizing');
}

Try / catch

try {
  await finalizeIncremental(projectRoot);
} catch (err) {
  if (String(err.message).includes('layers.json')) {
    console.error('Architecture artifacts missing; re-run the incremental pipeline.');
    process.exitCode = 1;
  } else throw err;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

AI-assisted analysis of Egonex-AI/Understand-Anything@07edf82a04 (2026-09-07). Data as JSON: /api/errors/556fdb40b94ac0f7. Report an issue: GitHub.