docs: close the last stale Codex parity claims (follow-up to #620) - #625

Summary

Follow-up to #620. Four polish items an advisor review raised after that PR was already merged, kept deliberately narrow: no behaviour changes, no new surface, six files.

1. A test comment contradicted the docs it was written beside. test_codex_plugin_hooks_contract.py still carried the original claim that session_lifecycle "survives" Codex's 3-second SessionEnd ceiling by spawning consolidation detached. The measurement taken later in feat(codex): full profile and the same eleven lifecycle hooks under Codex #620 contradicted that, and docs/codex-plugin.md already said the opposite. The rationale now lives on CODEX_SESSION_END_MAX, where the number it explains is defined.
2. The eleven-to-digit doc-claim fix was half-closed. plugins/hypermnesia-mcp-codex/.codex-plugin/plugin.json was not in check_doc_claims.py's SCANNED_FILES at all, and its description and longDescription both state the hook count to every installer a Codex marketplace shows it to. Those two, the package SECURITY.md, and the [Unreleased] CHANGELOG entry now use digits, and the manifest joins SCANNED_FILES.
3. A stale pointer. docs/codex-plugin.md said test_codex_plugin_contract.py imports HOOK_MODULES; the round-2 file split in feat(codex): full profile and the same eleven lifecycle hooks under Codex #620 moved that to _codex_plugin_support.py and the hooks contract test.
4. The SessionEnd limitation said what could be lost without saying what. Now concrete, see below.

Closes nothing; there is no open issue for these.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would change existing behavior)
• Refactor (no functional change; rules/coding-standards.md compliance)
• Documentation only
• Audit-finding closure (cite the finding ID)

What a session-end kill actually costs

The limitation note in #620 said session-end recording "can be lost" without naming what. I traced process_event in mcp_server/hooks/session_lifecycle.py rather than repeating the summary: only _spawn_consolidation is detached, and it runs last. Before it, inline and in order:

1. load_profiles() and load_session_log()
2. _append_session(...) then save_session_log(log), the session-log row
3. apply_session_update(...) then save_profile(domain_id, dp), the per-domain profile delta
4. _spawn_consolidation(...), the only detached part

So a hook killed at three seconds loses the session record itself, not a consolidation pass, and nothing retries it: the next SessionStart does not reconcile a missing row. The note now says that, and names the mechanism a fix would use (main() already dispatches on argv[1] == "--consolidate") while stating plainly that the decision is not made here.

This is the one item that is arguably more than polish. It is documented, not fixed, because moving steps 1 to 3 behind that detached re-invocation has its own durability trade-offs and belongs to whoever owns that module.

Test plan

• All existing tests pass.
• New tests added for new behavior. (No new behaviour; existing guards extended to cover the manifest.)
• Mutation survival check: I considered what mutations would NOT be caught.
• Manual verification of any UI / CLI / MCP-tool behavior changes.

The doc-claim gate now sees ten hook-count claims across six files, including the two shipped marketplace strings that were previously invisible to it:

README.md:43, 207, 318                          -> 11
docs/ROADMAP.md:13                              -> 11
plugins/.../README.md:34                        -> 11
plugins/.../SECURITY.md:5, 36                   -> 11
plugins/.../.codex-plugin/plugin.json:4, 25     -> 11
docs/codex-plugin.md:13                         -> 11

Mutation-checked, each reverted after:

CAUGHT  marketplace description goes stale
CAUGHT  marketplace longDescription goes stale
CAUGHT  package SECURITY.md goes stale

Gates, on the final state

$ python scripts/check_craftsmanship.py   -> Craftsmanship gate: OK (exit 0)
$ uvx [email protected] check                   -> All checks passed!
$ uvx [email protected] format --check          -> 3404 files already formatted
$ python scripts/check_doc_claims.py      -> doc claims OK (1 declared exemption)
$ python scripts/check_project_wiki.py    -> mirrors match their canonical sources
$ pytest tests_py/scripts/ tests_py/test_tool_surface.py -q
                                          -> 1048 passed, 3 skipped, 360 subtests passed
$ pytest tests_py/hooks/ -q               -> 2 failed, 558 passed, 13 subtests passed

The Lint job was also reproduced in a venv with only requirements/lint.txt installed, since this PR touches SCANNED_FILES and that job has no project package importable:

ruff format --check .              -> 3404 files already formatted, exit 0
ruff check .                       -> All checks passed!, exit 0
python scripts/check_doc_claims.py -> doc claims OK, exit 0

The two tests_py/hooks/ failures are pre-existing and environmental, not from this diff: deps/pydantic_core/_pydantic_core.cpython-312-darwin.so against a 3.13.7 interpreter in the local worktree. This branch changes no file under mcp_server/.

Audit notes

• Engineering review: the advisor's trace of session_lifecycle.py was re-verified against the source before being written into the doc, not relayed.
• Outstanding deferred findings: the uvx guard string is still duplicated across all 11 entries of both manifests, with only tests enforcing parity. Noted as debt in docs/codex-plugin.md during feat(codex): full profile and the same eleven lifecycle hooks under Codex #620; generating both manifests from one template remains the real fix and is out of scope here.

Coding-standards compliance

• §2.2 Layer dependency direction preserved.
• §3.2 No any or untyped dicts at boundaries in production code.
• §4.1 No file > 500 lines.
• §4.2 No function > 50 lines. (The craftsmanship gate caught this one at its stricter 40-line method cap while I was adding the comment; the rationale moved to the constant it explains.)
• §4.4 No function with > 4 parameters.
• §7 Local reasoning preserved.
• §8 Every numeric constant carries a source annotation.
• §9 No dead code, no TODOs without issue references.

Breaking changes

None. Documentation and one test comment; the only executable change is four strings in SCANNED_FILES and the manifest path added to it.

Reviewer checklist

• CHANGELOG.md updated under the appropriate section. (Amends the existing [Unreleased] entry rather than adding one; the change is prose in a claim feat(codex): full profile and the same eleven lifecycle hooks under Codex #620 already made.)
• Documentation updated.
• No secrets / credentials / PII in the diff.
• CI passes on the latest commit.

Co-Authored-By: Claude Sonnet 5 [email protected]
Claude-Session: https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH

🤖 Generated with Claude Code

https://claude.ai/code/session_01Cz7A6goxVzfKL9NT7k4zDH