#216 feat: package Claude Code integration as installable plugin

[Anonymous]

Originally created by: TheoV823

What

Packages the existing flat Claude Code integration as an installable Claude Code plugin at mneme-project-memory/integrations/claude-code-plugin/ — manifest, PreToolUse hook, mneme skill, and four namespaced commands (/mneme:context, /mneme:check, /mneme:record, /mneme:review). Additive packaging; core enforcement (DecisionRetriever, ConflictDetector, ADR compilation, benchmark) is untouched.

Correction pass (commit f311ee5)

The first commit (b708fd9) shipped a shell wrapper and an unverified >=0.4.2 install claim. This pass re-validated every assumption against the official Claude Code docs and the real version state, and corrected them:

1. Portable hook invocation — exec form, no shell

The launcher previously used a POSIX shell string (command -v python3 || command -v python). Per the official hooks reference, shell-form hooks run under sh -c on macOS/Linux but Git Bash on Windows, or PowerShell when Git Bash isn't installed — where that syntax is invalid. (My earlier "bundled POSIX shell on all platforms" claim was wrong.)

Now the hook uses exec form, which resolves the command on PATH and spawns it directly with no shell on any platform:

{ "type": "command", "command": "mneme-hook", "args": [], "timeout": 30 }

scripts/run_mneme_hook.py was deleted — redundant once mneme-hook is invoked directly. No second runtime layer.

2. Mode resolution moved into the adapter (hook.py)

New resolve_mode() with precedence MNEME_HOOK_MODE > CLAUDE_PLUGIN_OPTION_MODE > strict. The plugin's mode userConfig reaches the subprocess as CLAUDE_PLUGIN_OPTION_MODE (exported to plugin subprocesses per the reference). Unrecognized values fall back to strict. Logic lives in the Claude Code integration adapter, not core enforcement.

3. Preserved semantics

Exit code 2 is the only blocking result; fail-open on every execution failure (missing binary/memory, malformed event, materialization failure, timeout); strict and warn modes intact. No auto-install, bundling, telemetry, or new capabilities.

Final cleanup (commits 2823e9a, aad959b)

• Manifest declares version: "0.1.0". An SHA-versioned manifest (no version) was briefly tried, but claude plugin validate --strict (CLI 2.1.198) treats the "no version specified" warning as an error, so the strict gate requires an explicit version. A contract test asserts the version is present and valid semver.
• README fail-open wording corrected. A missing/unreadable target file applies to Edit/MultiEdit reconstruction, not Write (Write creates from tool_input.content).

Verified version state

Source	Version
pyproject.toml (branch + at v0.4.2 tag)	0.4.0
CHANGELOG latest released	v0.4.2 (2026-05-05)
Latest git tag	v0.4.2
Latest GitHub release	v0.4.2 (Latest)
PyPI (mneme-hq)	0.4.0 only
Branch contains v0.4.1 + v0.4.2 hook fixes?	Yes (both tags are ancestors; __main__.py present)

Classification: Case B. The v0.4.2 fixes are in source but not published to PyPI, and the branch is actually past 0.4.2 (unreleased mneme init). pyproject is intentionally left at 0.4.0 — bumping to 0.4.2 would mislabel the build (which the branch source exceeds), and the established release process never bumped pyproject (it was 0.4.0 even at the v0.4.2 tag). There is no PyPI-publish workflow; publishing is a manual maintainer action.

README no longer implies an uninstallable version. It documents installing Mneme from the repository until mneme-hq >= 0.4.2 is published to PyPI (recommended because PyPI's 0.4.0 still has the exit-propagation bug). Publishing 0.4.2 remains a separate, explicit maintainer action.

Testing

• Integration suite: 21 → 45 passed (added mode-precedence, main-level fail-open, and deterministic plugin-contract/regression-guard tests incl. the no-explicit-version guard).
• Full suite: 375 passed, 0 failed (52 pre-existing benchmark warnings).
• Package build: python -m build → mneme_hq-0.4.0-py3-none-any.whl + sdist OK.
• Live smoke test (faithful exec-form path — spawns the source mneme-hook entry with the event on stdin): clean Write→0, violating Write strict→2, violating Write warn-via-CLAUDE_PLUGIN_OPTION_MODE→0, clean Edit→0, violating Edit strict→2, no-.mneme→0, plugin-option strict→2. All as expected.

External validation (maintainer, Claude Code CLI 2.1.198)

• claude plugin validate --strict — passes with version: "0.1.0" restored (the missing-version warning is what --strict was failing on).
• claude --plugin-dir — plugin loads: reads hooks/hooks.json, registers 1 hook, loads 4 commands and 1 skill.
• Still pending: the authenticated live Write-succeeds / violation-blocked-in-strict smoke test — the CLI validation environment isn't authenticated to Claude Code, so the model-driven edit couldn't run. (Equivalent behavior is covered by the source-level exec-form smoke test above.)
• macOS/Linux — not exercised; exec form is platform-independent by construction, but only Windows was run directly.

Remaining manual action (not in this PR)

Publish mneme-hq >= 0.4.2 to PyPI, then flip the README install line to pipx install "mneme-hq>=0.4.2".

🤖 Generated with Claude Code

[Anonymous]

Originally posted by: github-actions[bot]

mneme self-governance check

Mode: warn - verdicts are visible but do not block merge. Rollout plan: .mneme/README.md.

Summary: 1 pass, 0 warn, 0 fail, 0 unknown

verdict	file
✅ PASS	mneme-project-memory/mneme/integrations/claude_code/hook.py

_{Generated by .github/workflows/mneme-check.yml · query = PR title + file path · scope = repo-governance paths.}