doctor's own fix breaks git fetch and git pull, then reports ok

[MongLong0214]

Found by cloning the repository fresh and doing exactly what doctor said, in order.

Reproduction — no editing, only following instructions

git clone https://github.com/MongLong0214/commitlore.git && cd commitlore
node dist/commitlore.mjs doctor
  warn  notes fetch refspec — origin does not fetch refs/notes/commitlore
        fix: git config --add remote.origin.fetch '+refs/notes/commitlore:refs/notes/commitlore'

git config --add remote.origin.fetch '+refs/notes/commitlore:refs/notes/commitlore'

git fetch origin   → fatal: couldn't find remote ref refs/notes/commitlore   exit 128
git pull           → fatal: couldn't find remote ref refs/notes/commitlore   exit 1

node dist/commitlore.mjs doctor
  ok    notes fetch refspec — origin fetches refs/notes/commitlore

The user's git pull is now permanently broken, and doctor says the check is ok.

An explicit (non-wildcard) refspec naming a ref the remote does not have is fatal to the entire fetch, not just that ref. origin has no refs/notes/commitlore because nothing has ever pushed one.

The fix line is wrong; a wildcard is not

+refs/notes/*:refs/notes/*                          → git fetch exit 0
+refs/notes/commitlore:refs/notes/commitlore        → git fetch exit 128

Verified both, in that order, in the same clone. A wildcard refspec matching nothing is not an error; an explicit one is.

Whether the wildcard is the right recommendation is a separate question — it fetches every notes ref, including other tools'. The alternative is to add the explicit refspec only after confirming the remote has the ref, and to tell the user to push one first otherwise.

The deeper defect is the second doctor run

This is the third instance today of the same shape:

	check	what it verifies	what it misses
#58	validate	the trailer is well-formed	the record it names exists
#60	validate	the message parses	two records became one
this	doctor	the config line is present	fetching actually works

doctor exists to tell a user whether their setup works. A check that reads back its own written config and calls it ok is checking that git config works, not that CommitLore does. Every doctor check that recommends a fix must verify the outcome of that fix, not its trace.

That principle belongs in the check-class model being written for #58/#60 — doctor is squarely in the Conservation class (needs a before and an after) and has been implemented as if it were in the Shape class.

[MongLong0214]

Escalation — doctor --fix applies it automatically

I filed this as bad advice a user might follow. It is worse: the tool applies it itself.

$ commitlore context
commitlore: the notes mirror has not been fetched here …
fix: commitlore doctor --fix, then git fetch

$ commitlore doctor --fix
ok      notes fetch refspec — origin fetches refs/notes/commitlore
        fixed by --fix
                                                                   exit 0

$ git fetch origin
fatal: couldn't find remote ref refs/notes/commitlore              exit 128

context recommends doctor --fix. doctor --fix writes the explicit refspec, reports the check as ok, exits 0, and the repository's git fetch and git pull are broken from that moment on. The user never typed a git command; the repair command did it.

It bites exactly the common case

An explicit refspec is only fatal when the remote lacks the ref. The remote lacks refs/notes/commitlore until somebody pushes one — which is the state of every repository that has just adopted CommitLore. The failure is not an edge case; it is the first-run path, and the tool walks the user into it with a command it recommends by name.

Verified in a clean two-user setup

git init --bare origin
clone → userA → commit with a record → push
clone → userB → commitlore context
  exit 3, warns the mirror was not fetched, recommends doctor --fix
userB → commitlore doctor --fix → ok, exit 0
userB → git fetch → exit 128, permanently

Also found here: a fourth exit code

context returned exit 3 for "answered, but the notes mirror was not fetched". #65 documented 0, 1, and 2 in conflicting roles across commands; 3 is a fourth, undocumented, on a query command. The exit-code convention needs to cover this case explicitly — "answered with a completeness caveat" is a legitimate state and deserves a defined code, not an ad-hoc one.

[MongLong0214]

The README's own install sequence does this

Not hypothetical, not a flag a curious user might find. It is step 3 of four in README.md §"Install from the clone", and it is printed in all four language editions.

Ran the four lines verbatim into a clean directory:

git clone https://github.com/MongLong0214/commitlore ~/.commitlore     # ok
node ~/.commitlore/dist/commitlore.mjs --version                        # 0.1.0
node ~/.commitlore/dist/commitlore.mjs doctor --fix                     # exit 0, "fixed by --fix"
node ~/.commitlore/dist/commitlore.mjs context src/auth --no-index      # no active records

After line 3:

git fetch origin  →  fatal: couldn't find remote ref refs/notes/commitlore   exit 128

Every reader who follows the published instructions ends with a repository whose git fetch and git pull are broken. They ran no git command themselves; line 3 did it.

Why it fires even here

git ls-remote origin 'refs/notes/*'   →  (empty)

CommitLore has never pushed its own notes mirror. Neither its origin nor a fresh clone has the ref, so the explicit refspec is fatal in the project's own repository, following the project's own instructions.

For contrast, gitseed's origin does carry refs/notes/commitlore (b909d2c4), which is why the failure never appeared while dogfooding there. The bug is invisible in exactly the repository where it was being tested and visible in every new adopter's.

Correction to the project's dogfooding record

HANDOFF.md §5 lists notes mirror — refspec configured and ref exists. For this repository the local mirror is empty (0 notes) and the remote ref does not exist. That line was true of gitseed and was recorded as true of the tool.

Blast radius

This is now three defects on one path, all reachable from published instructions:

• doctor --fix writes a refspec that breaks fetch (this issue)
• doctor then reports the check ok
• the README hands the user the command

Fixing the refspec fixes all three, and the README needs no edit once the written config is safe. Until then the README is actively harmful and that is worth a same-day change independent of the code fix.