fix(plugins): make Codex hooks and memory notes reliable

[phernandez]

Why

The Codex hooks had accumulated launcher and version-floor behavior that made a simple question—can the hook run the Basic Memory command it needs?—hard to answer. A fail-open test could also pass while the installed package lacked the hook command entirely.

The notes produced around Codex work had a second problem: checkpoints read like mechanical status dumps, decisions were separated from semantic observations, relations used observation syntax instead of graph syntax, and projected notes did not record which user and host produced them.

What Changed

• Pin both Codex PEP 723 hook scripts to one Basic Memory Git SHA and invoke the CLI in-process.
• Add just set-codex-hook-version <ref> and use it from stable and beta release recipes.
• Add username and hostname frontmatter to projected hook notes and the Codex session schema.
• Add a plugin-owned, user-customizable bm-writing skill shared by checkpoint, decision, and lightweight memory capture.
• Rewrite checkpoint guidance around a useful problem → approach → current-state narrative, typed observations, and real wiki-link relations.
• Strengthen plugin validation and regression tests for shared hook refs, provenance metadata, note structure, and relation syntax.

Implementation Details

• plugins/codex/hooks/{session_start,pre_compact}.py now contain only the pinned uv dependency, the hook verb/harness arguments, and the fail-open in-process Typer invocation. There is no executable discovery, launcher parsing, or separate version parsing.
• just set-codex-hook-version delegates dependency editing to uv add --script, keeping both scripts on the same ref. Development can pass the current main SHA; stable and beta recipes pass the release tag and stage both scripts.
• src/basic_memory/hooks/projector.py records username and hostname in artifact metadata, with an environment fallback so optional username discovery cannot abort a flush.
• plugins/codex/skills/bm-writing is the customization point for voice and narrative quality. Task-specific skills still own their schemas and evidence requirements.
• Checkpoint relations now use - relates_to [[Target Note]]; decisions, blockers, results, and next steps remain semantic observations.

Testing

Automated

• just fast-check: passed (ruff, formatting, and type checking).
• uv run pytest -q tests/test_claude_plugin_hooks.py tests/test_codex_plugin_package.py plugins/codex/hooks/test_codex_session_start.py plugins/codex/hooks/test_codex_pre_compact.py tests/hooks/test_projector.py tests/test_update_versions.py: 66 passed.
• just package-check: passed all consolidated agent package checks.
• just set-codex-hook-version "$(git rev-parse origin/main)": updated both scripts to the same current main SHA.
• just release-dry-run v0.99.0: passed.

Manual

• Ran SessionStart and PreCompact through their uv scripts with Codex hook payloads: both exited successfully and captured their envelopes.
• Flushed the hook inbox and read back the projected session note: the queue emptied and frontmatter included the local username and hostname.

Risks / Follow-ups

• A cold hook run needs GitHub access to resolve the pinned revision; subsequent runs use uv's cache.
• Existing notes are not rewritten. Provenance and the improved writing contract apply to newly projected or newly written notes.
• The release recipes intentionally move the Codex hook ref; normal package version updates no longer rewrite these two scripts as PyPI version floors.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: eeeac29f67

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[phernandez]

@codex review

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ea03de0162

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[phernandez]

@codex review

[chatgpt-codex-connector]

Codex Review: Didn't find any major issues. Nice work!

Reviewed commit: cc71a60d9f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".