docs: bring the published docs up to what 4.10.0 actually does - #343
Merged
Merged
Conversation
added 5 commits
September 12, 2026 23:47
An audit of the eight public documents against the 214 commits since v4.9.4 found twelve gaps. Two were wrong rather than merely missing, and one was the kind this project keeps writing rules about. Wrong: - CHANGELOG and API_REFERENCE both listed three hook outcomes. There are four — `notified` was added with the capture-liveness work and neither document followed. A reader counting runs would find that writes + skips + errors does not equal runs, with nothing to explain the difference. - The doctor `capture` example omitted `notifies` and `lastNotifiedAt`, which every `--json` response carries. Silent, and worth its own line: a derived observation over 10,000 characters is truncated with a trailing ellipsis and nothing says so — while a structured observation of the same length is rejected. API_REFERENCE documented the rejection and not the truncation, so the reasonable inference from it was wrong in the direction that loses data. Both the `note` field and the note-file path now say it. Missing: - `replace` on a memory archived with `forget` is refused; no document said so. - `replace` keeps the type the memory already has (landed today); every surface had followed except CHANGELOG. - Four behaviour changes since the 4.10.0 section was written had no entry at all: the receipt reporting the stored title, the over-cap message counting observations, the schemas declaring their forms through anyOf, and the JSON import path rejecting notes-only flags. - ARCHITECTURE's remember flow predated both `note` and `replace`, and its Session Summary section did not mention the two further writes a Stop now makes. - The three READMEs still described `remember` as observations-only, although the `briefing` row beside it had been updated for the index. - SKILL.md did not mention `briefing --index`. dist/skills-manifest.json is regenerated because it embeds SKILL.md.
…nged The certified hash covers the extracted tool table, so the three READMEs and API_REFERENCE went stale when the `remember` row started mentioning `note` and `replace`. Reviewed before signing: the tool names are unchanged, and the new description matches what the code does.
… commit The fixes written to close twelve documentation gaps were themselves unreviewed code, and three of them were wrong. - API_REFERENCE said a notify-only hook "can be reported silent" eighteen lines above saying it is not silent. The code settles it: no hook that notifies is in SILENT_ELIGIBLE_HOOKS, which is post-commit, session-summary and pre-compact (capture-liveness.ts:293). The sentence now says that instead of contradicting its neighbour. - API_REFERENCE still said `replace: true` on an unknown name "simply creates the memory". It does not: with no stored type to inherit, operations.ts:233 rejects the call unless `type` was passed — which is what the CHANGELOG entry in the same commit said, so the two documents contradicted each other and the contradiction was introduced here. - ARCHITECTURE credited the remember nudge to src/core/turn-signal.ts. It lives in scripts/hooks/_stop-notes.js:384; turn-signal.ts is the Hermes chat-turn classifier, and it writes memories, so the wrong file was named and its real behaviour is the opposite of what the sentence claimed. The same sentence called both Stop actions "writes" while saying one stores nothing, and said both respect MEMESH_AUTO_CAPTURE=false when only the ingest is gated on it (_stop-notes.js:440; the nudge sits outside at :471).
A fresh-eyes review and a simplification pass, both on the same diff, and both found things in prose I had written to close earlier findings. Six defects in about fifty lines now. - API_REFERENCE derived the opposite conclusion from its own premises: it said a notify-only hook "is not silent" because notifies count as triggered and not as writes — which are exactly the two conditions that make a hook silent (capture-liveness.ts:735-742). The sentence was also a second copy of what the same file says twenty lines earlier, and the copy is the one that was wrong. Deleted rather than corrected; the correct statement stays where it was, and the three-item hook list it repeated is no longer repeated either. - CHANGELOG said the schemas "state the two forms". There are three, and the same bullet listed all three: note, name + type, name + replace. The code comment at handlers.ts:150 says "Three complete forms". - ARCHITECTURE's replace flow had the order backwards. The previous version is snapshotted BEFORE clearEntityData, which has to be true because the clear deletes the observations being snapshotted; and replaced_history is written AFTER createEntity, not before (operations.ts:259-264, :331-337). Following the documented order would produce an empty history. Also drops a duplicated truncation note, the blank line that was making the 4.10.0 list render loose, and the aside naming turn-signal.ts — no document mentions that file, so the sentence created the confusion it was resolving.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #342.
Twelve gaps found by auditing the eight public documents against the 214 commits since v4.9.4, each checked against the code rather than against another document.
Wrong, not merely missing
CHANGELOG.mdanddocs/api/API_REFERENCE.mdboth listed three hook outcomes. There are four —notifiedarrived with the capture-liveness work and neither document followed. A reader counting runs findswrites + skips + errorsdoes not equalruns, with nothing to explain the gap.captureexample omittednotifiesandlastNotifiedAt, which every--jsonresponse carries.Silent, and the reason this one is first
A derived observation over 10,000 characters is truncated with a trailing ellipsis, and nothing in the response says so. A structured observation of the same length is rejected. API_REFERENCE documented the rejection and not the truncation, so the reasonable inference from it was wrong in the direction that loses data. Verified in
src/core/note-derive.ts:78-80;NOTE_OBSERVATION_MAX_CHARSappears nowhere insrc/transports/schemas.ts, so no validation stands between a caller and it. Both thenotefield and the note-file path now say it.Missing
replaceon a memory archived withforgetis refused — no document said so.replacekeeps the type the memory already has. Every surface had followed except CHANGELOG.anyOf, and the JSON import path rejecting notes-only flags.docs/ARCHITECTURE.md's remember flow predated bothnoteandreplace, and its Session Summary section did not mention the two further writes a Stop now makes.rememberas observations-only, although thebriefingrow beside it had been updated for the index.skills/memesh/SKILL.mddid not mentionbriefing --index.Verification
npm run verify:release→exit=0node scripts/run-tests-isolated.mjs→exit=0, 248 files / 3791 passed / 9 skipped, zeroErrors N errorslinesdist/skills-manifest.jsonis regenerated because it embeds SKILL.md. Four certified surfaces are re-signed: the hash covers the extracted tool table, and therememberrow changed.