query reports a v4 index against a v3 reader and falls back forever without rebuilding

[MongLong0214]

Every commitlore_query call in this repository returns:

"diagnostics": [
  "the index is unavailable (index was built by schema v4, this build expects v3);
   answering with a full scan"
]

The answer is still correct — it fell back to scanning history — but the index that exists on disk is newer than the build that reads it, and the build never reconciles them.

Reproduction

• macOS, commitlore --version → 0.8.2
• Index present at .git/commitlore/index.db, 946176 bytes, written while 0.8.2 was the installed version
• Call commitlore_query with {"kind": "context", "path": "<any tracked path>"}
• The diagnostic appears on every call

Why the direction matters

A v3 reader meeting a v4 index means the writer is ahead of the reader in the same installation. Either two components of one release disagree about the schema version, or an index written by a newer build survived a downgrade with nothing to invalidate it. Both leave a stale artifact that is never rebuilt: the fallback works, so nothing ever forces the index to be regenerated, and it silently stays unusable.

Cost

The fallback is a full history scan. On this repository that is currently cheap, but the point of the index is that it does not stay cheap. A degradation that always succeeds is one nobody notices until the scan is the bottleneck.

What would resolve it

Either a version check that rebuilds the index when the schema does not match instead of only reporting it, or a stated compatibility rule that makes the mismatch impossible within one release. Reporting-and-falling-back leaves the artifact permanently stale.

What I could not determine

Which component wrote the v4 index — whether an earlier 0.8.x on this machine wrote v4 and 0.8.2 reads v3, or whether the CLI and the MCP server within 0.8.2 disagree. I did not attempt a rebuild, so whether deleting .git/commitlore/index.db regenerates a v3 index is unverified.

[MongLong0214]

Classified against the A–Z review (document_version 4.1.0, evidence main@b578ca9890) as a symptom of F-001 — runtime identity and upgrade convergence (P0), not as an independent defect.

The finding records this exact machine state:

PATH CLI            0.8.2
Git hook pin        0.8.0
Claude plugin cache 0.8.0
Codex plugin cache  0.8.2
MCP asset lookup    0.6.0 or dev-<hash>
Index writer        schema v4
MCP reader          schema v3

Every one of those is called commitlore, which is why the symptom reads as a bug in whichever surface the user happened to be looking at.

This issue stays open and its evidence stays as reported. It is not a duplicate to be closed — it is the reproduction that proves the convergence failure is real rather than theoretical, and it is what the fix has to satisfy. Work is tracked under F-001 with the completion condition:

CLI identity == hook identity == live MCP identity == plugin identity

matching on entrypoint and package root, not on a version string alone.

[MongLong0214]

Linked to #635 as a candidate of the same root cause — several execution surfaces running different builds — rather than as a duplicate. This issue's own acceptance criteria stay as written and are not absorbed by the umbrella.

Measured on one machine at one moment: four commitlore runtimes answering as MCP servers (0.6.0, v0.8.1, v0.8.2, dev-3b70a1be), two of them from package roots that no longer exist on disk, alongside a PATH CLI at 0.8.2 and a Claude plugin cache at 0.8.0.

If the convergence work closes this symptom, that will be shown against this issue's criteria before it is closed here.