From 55e6dc7b50bd7bc0936b0d3422ecf7f2c1fe42f7 Mon Sep 17 00:00:00 2001 From: MongLong0214 Date: Sun, 16 Aug 2026 00:06:23 +0900 Subject: [PATCH] Say what an upgrade does not reach, and what to run about it An upgrade updates the CLI and reaches neither hooks already installed in a repository nor sessions already running. Both are visible in doctor and neither was written down, so a user meeting the warnings had no way to know they were expected rather than broken. The hook records the exact bundle it ran from, which pins that repository to one release, and the installer cannot fix it -- it has no way to know which repositories have hooks. That limit is stated rather than worked around. Also records why the version is there at all, because the obvious repair is wrong and was tried: recording the bin wrapper instead made hooks fail under the restricted PATH a hook actually runs in. The recorded path exists to be independent of PATH, and the interpreter is recorded beside it for the same reason. A version-free path that keeps both properties needs a stable directory the installer maintains, which is #693's remaining work rather than something to improvise. Limit: an upgrade cannot reach a repository's hooks or a running session Blast: system Undo: easy Certainty: firm Provenance: authored Record-Id: r-693docs --- docs/COMPATIBILITY.md | 43 +++++++++++++++++++++++++++++++ docs/handoff/20260815-after-v1.md | 42 ++++++++++++++++++++++++++++++ 2 files changed, 85 insertions(+) diff --git a/docs/COMPATIBILITY.md b/docs/COMPATIBILITY.md index 26a615b8..c69e1afc 100644 --- a/docs/COMPATIBILITY.md +++ b/docs/COMPATIBILITY.md @@ -97,6 +97,49 @@ What still holds: execution correctness is unaffected. A registration that works is verified normally, and one that is genuinely broken is still reported as unverified — a user is never told a broken registration is healthy. +## After upgrading, run `doctor` (#693) + +An upgrade updates the CLI. It does not reach two things: + +- **Hooks already installed in a repository.** `commitlore hooks install` records + the exact bundle it ran from, which pins that repository to one release. The + installer cannot fix this for you — it has no way to know which repositories + have hooks. +- **Sessions already running.** A host loads its runtime once and keeps it. + +So after installing a new version: + +```sh +commitlore doctor +``` + +Two warnings are the ones to expect and act on: + +``` +runtime identity — hook identity differs from CLI: hook v; CLI v + fix: commitlore hooks install # run it in that repository + +live MCP runtime identity — N live CommitLore MCP runtime(s) are unusable + restart those sessions # a host keeps the runtime it loaded +``` + +Neither is a defect in the release. Both are state a release cannot reach, and +`doctor` naming them is the product doing what it can — which is to say what it +knows rather than to guess that everything is current. + +### Why the hook records a version + +It is deliberate. The recorded path makes the hook independent of `PATH` and of +whatever `node_modules/.bin/commitlore` sits above the repository, and the +interpreter is recorded beside it because a hook runs where `PATH` may carry no +`node` at all. A launcher that resolves through `PATH` would undo both — which +was measured, not assumed: recording the `bin` wrapper made hooks fail under the +restricted `PATH` a hook actually runs in. + +Making the recorded path version-free without losing those properties needs a +stable directory the installer maintains, and that is tracked in #693 rather than +improvised. + ## Prerequisites Two columns, because **required** and **checked** are not the same claim. Only diff --git a/docs/handoff/20260815-after-v1.md b/docs/handoff/20260815-after-v1.md index 8957e55d..b623b1dd 100644 --- a/docs/handoff/20260815-after-v1.md +++ b/docs/handoff/20260815-after-v1.md @@ -75,6 +75,48 @@ That is the sharpest thing this release taught, and it is worth more than the issue count: **the suite starts from nothing every time, which is what makes it repeatable and what makes it blind.** +## v1.0.1, and what the release itself taught + +v1.0.0 shipped and then three defects appeared that no test could have caught, +all at the install boundary. Fixing them produced two more of the same kind. The +whole set became v1.0.1: + +``` +#683 the release workflow failing on a release that already existed +#684 hermes install refusing the config it wrote +#687 the skills root taken from the running bundle, not --data-root +#688 an installed plugin treated as a reason to stop rather than upgrade +#690 claude-code wired by nothing, in neither hosts nor notDetected +``` + +The controls all inverted after v1.0.1: exit code 1 → 0, claude-code absent → +installed healthy, plugin cache unmoved → new generation present, hermes failed → +healthy, doctor unusable 4 → 2 (the remainder being sessions that predate the +upgrade). + +**#688 alone did nothing.** It repaired a function nothing called; #690 is what +made it reachable. Measured, not inferred — the cache still did not move after +#688 landed. + +## One pattern, four times + +``` +.mcp.json "commitlore" the wrapper → survived every upgrade +Hermes external_dirs .../v0.8.2/hermes/skills versioned → broke (#686) +plugin cache a copy of the code a copy → stalled (#660) +hook commitlore.bin .../v0.8.2/dist/commitlore.mjs versioned → open (#693) +``` + +The configuration that pinned nothing is the one that survived. Every other one +needed a fix. + +#693 is the one still open, and the obvious repair is wrong: recording the `bin` +wrapper makes hooks fail under the restricted `PATH` a hook runs in, because the +wrapper is a shell script and `commitlore.node` exists precisely because `PATH` +may carry no `node`. That was asserted in a PR, then disproved by CI. What it +needs is a version-free path to a `.mjs`, which needs a directory the installer +maintains — gated with #691. + ## Traps this repository sets Each cost a cycle today.