{"record":{"id":"5edbea41bb085eb4","repo":"Egonex-AI/Understand-Anything","slug":"fingerprint-patch-does-not-match-the-incremental-p","errorCode":null,"errorMessage":"Fingerprint patch does not match the incremental plan commits","messagePattern":"Fingerprint patch does not match the incremental plan commits","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"understand-anything-plugin/skills/understand/finalize-incremental.mjs","lineNumber":392,"sourceCode":"    analyzedAt: new Date().toISOString(),\n    gitCommitHash: plan.headCommit,\n  };\n}\n\nasync function main() {\n  const args = process.argv.slice(2);\n  if (args.length !== 1 || args[0].startsWith('--')) {\n    throw new Error('Usage: node finalize-incremental.mjs <projectRoot>');\n  }\n  const projectRoot = realpathSync(args[0]);\n  const uaDir = resolveUaDir(projectRoot);\n  const intermediateDir = join(uaDir, 'intermediate');\n  const plan = readJson(join(intermediateDir, 'incremental-plan.json'));\n  const patch = readJson(join(intermediateDir, 'fingerprint-patch.json'));\n  const scan = readJson(join(intermediateDir, 'scan-result.json'), { totalFiles: 0 });\n  if (!plan || !patch) throw new Error('Incremental plan or fingerprint patch is missing');\n  if (patch.baseCommit !== plan.baseCommit || patch.headCommit !== plan.headCommit) {\n    throw new Error('Fingerprint patch does not match the incremental plan commits');\n  }\n\n  if (plan.action === 'FULL_UPDATE') {\n    throw new Error('FULL_UPDATE must run the full /understand pipeline');\n  }\n  if (plan.action === 'SKIP' && isGeneratedOnly(plan)) {\n    process.stdout.write('Generated artifacts only: analysis baseline unchanged\\n');\n    return;\n  }\n\n  const graphPath = join(uaDir, 'knowledge-graph.json');\n  const importMapRefreshPaths = Array.isArray(plan.importMapRefreshPaths)\n    ? plan.importMapRefreshPaths\n    : [];\n\n  if (plan.action === 'SKIP') {\n    const previousGraph = readJson(graphPath);\n    if (!previousGraph || !Array.isArray(previousGraph.nodes) || !Array.isArray(previousGraph.edges)) {","sourceCodeStart":374,"sourceCodeEnd":410,"githubUrl":"https://github.com/Egonex-AI/Understand-Anything/blob/07edf82a04371b6f69779b067bdc8a1a8753a9db/understand-anything-plugin/skills/understand/finalize-incremental.mjs#L374-L410","documentation":"finalize-incremental.mjs refuses to run when the fingerprint patch and the incremental plan were computed against different git ranges. The script compares patch.baseCommit/headCommit against plan.baseCommit/headCommit and throws if either differs, because applying a patch from the wrong range would corrupt the fingerprint baseline. It is a safety invariant of the incremental update pipeline.","triggerScenarios":"Running finalize-incremental.mjs when fingerprint-patch.json was regenerated after a new commit (or on a different branch/rebase) while incremental-plan.json is stale, or vice versa; interleaving two /understand incremental runs; manually copying intermediate files from another run.","commonSituations":"A rebase or pull changed HEAD after the plan was computed but before finalize; a developer re-runs only the finalize step hours later after commits landed; concurrent Claude sessions share the same .ua/intermediate directory; hand-editing or restoring files from a backup.","solutions":["Delete .ua/intermediate/incremental-plan.json and fingerprint-patch.json and rerun the incremental planning step so both files are produced from the same commit range","Verify git HEAD matches plan.headCommit before finalizing; if commits landed meanwhile, regenerate the plan","Avoid running finalize from a different branch or worktree than the one that produced the plan","Never reuse intermediate artifacts across runs; clean .ua/intermediate/ before restarting"],"exampleFix":"# before (stale mixed artifacts)\nnode finalize-incremental.mjs .\n# Error: Fingerprint patch does not match the incremental plan commits\n\n# after: regenerate both artifacts in one run\ngit checkout <plan-branch> && rm -rf .ua/intermediate && rerun /understand incremental pipeline","handlingStrategy":"validation","validationCode":"const plan = JSON.parse(fs.readFileSync('.ua/intermediate/incremental-plan.json','utf8'));\nconst patch = JSON.parse(fs.readFileSync('.ua/intermediate/fingerprint-patch.json','utf8'));\nif (patch.baseCommit !== plan.baseCommit || patch.headCommit !== plan.headCommit) {\n  throw new Error('Plan/patch commit mismatch; regenerate intermediate artifacts');\n}","typeGuard":"const commitsMatch = (plan, patch) =>\n  !!plan && !!patch &&\n  patch.baseCommit === plan.baseCommit &&\n  patch.headCommit === plan.headCommit;","tryCatchPattern":"try {\n  await run('node finalize-incremental.mjs .');\n} catch (err) {\n  if (String(err.message).includes('does not match the incremental plan commits')) {\n    fs.rmSync('.ua/intermediate', { recursive: true, force: true });\n    await rerunIncrementalPipeline();\n  } else throw err;\n}","preventionTips":["Always regenerate plan and patch in the same pipeline run","Never finalize from a different branch or after commits landed without replanning","Serialize /understand runs; concurrent runs share .ua/intermediate/","Clean .ua/intermediate/ when resuming after a git rebase or pull"],"tags":["incremental","git","pipeline","stale-state"],"backgroundTag":"checksum-mismatch","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"}