Egonex-AI/Understand-Anything · error

Architecture update requires tour.json; baseline not advance

Error message

Architecture update requires tour.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 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.

Source

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

      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,
      },
      nodes: assembled.nodes,
      edges: assembled.edges,
      layers: assignLayers(rawLayers, assembled.nodes, assembled.edges),

View on GitHub (pinned to 07edf82a04)

Solutions

1. Re-run the incremental pipeline so the tour step executes and writes .ua/intermediate/tour.json, then re-run finalize-incremental.mjs.
2. Regenerate the incremental plan with rerunTour set to false (or run the full /understand pipeline) if tour regeneration is not needed.
3. Remove the stale .ua/intermediate/incremental-plan.json so the next prepare-incremental.mjs run creates a plan consistent with the artifacts actually produced.
4. Verify the tour step writes to the resolved data directory (.ua/intermediate/, or .understand-anything/intermediate/ for legacy projects).

Example fix

// before: finalize with rerunTour: true but no tour.json
node finalize-incremental.mjs .   // throws: Architecture update requires tour.json

// after: produce the artifact first
node prepare-incremental.mjs .
# run tour-builder agent (writes .ua/intermediate/tour.json)
node finalize-incremental.mjs .

// 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.rerunTour && !existsSync(join(uaDir, 'intermediate', 'tour.json'))) {
  throw new Error('tour.json missing: re-run the tour step before finalizing');
}

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

When it happens

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

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

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

• Architecture update requires layers.json; baseline not advan
• assembled-graph.json is missing or invalid; baseline not adv
• Unresolved incremental symbol loss; baseline not advanced
• Benchmark stage failed: ${stage.name}
• Incremental plan or fingerprint patch is missing

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