git:20260818.6945463 to git:20260821.1a05a80

- Runtime adapter over the `codemap-py integrate` engine (`src/codemap_py/integration.py`). Either host runtime — Claude Code or Codex — can target Claude Code, Codex, or both; this skill never invokes the other runtime's model, only its native plugin-manager CLI.

-

- Five modes, matching the pinned CLI surface exactly; the legacy `check` mode is removed without an alias:

- `--approve` is valid only with an explicit mutation mode (`apply`/`sync`), a saved plan artifact, and the SHA-256 shown to the user for that plan. It never authorizes new targets, remote publication, Git history/remote mutation, marketplace-file editing, user instruction-file editing, or data deletion.

- Closed integration/reinstall set: Claude consumers `foundry`, `oss`, `develop`, `research` (provider `codemap-py`); Codex consumer `codex-rig` (provider `codemap-py`). This is an explicit mapping cross-checked against both marketplace manifests and plugin manifests before any mutation — not a discovery/extension registry. `--runtime codex` scopes to the `codex-rig` consumer only; `--runtime claude` to the four Claude consumers; `--runtime both` (or omitted) to all five.

- Safety invariants (enforced by the shared engine, not this skill — surfaced here so the user sees the contract):

- - `plan` records schema/protocol version, op ID, exact targets, before-state hashes, desired versions/refs/hashes, exact argv, ordered ops, rollback identities, expected post-state, and a plan SHA-256.

- - Every mutation revalidates target + before-state immediately before acting; drift invalidates the approval.

- - Source writes use before-images and atomic per-file replace; `apply` refuses foreign/modified markers, path escapes, symlinks, installed-cache roots, dirty working-tree overlap, and unverified product identity.

- - `sync` refuses applying a plan whose source isn't actually built into the selected candidate, whose installed bytes don't match the selected hash, or that names a mutable/default-branch source as release/rollback evidence. No implicit "latest".

- - First-target success + second-target failure stops immediately; rollback only performs actions the approved plan already contains. Completion and rollback are both claimed only after a post-state hash verification.

- - "Push" here means two local operations only: (1) updating allowlisted, version-controlled consumer source integration from the `codemap-py.integration.v2` contract, and (2) installing/reinstalling those built plugin versions in the user's local runtime(s) via native CLI operations. It never means `git push`, remote marketplace mutation, release publication, or direct installed-cache edits.

- Codex has no `bin/` PATH entry and no `$CLAUDE_PLUGIN_ROOT`-equivalent environment variable. Resolve this skill's installed plugin-root path once, substitute it for `PLUGIN_ROOT` below, and keep it in reasoning — shell state does not persist across tool calls. Codex has no `AskUserQuestion` tool: every approval gate below means "print the plan summary and SHA-256 in chat, then wait for the user's next message before running `apply`/`sync`."

- Codex-specific runtime CLI discovery: when `--runtime` includes `codex`, discover the active `codex-rig` installation with the native Codex CLI, never by editing config by hand:

- If a documented `--json` option is unavailable for the installed Codex CLI version, fall back to the text form and mark structured comparison unavailable rather than inventing a flag.

-

- Codex-specific fresh-session instruction: Codex requires a fresh app/session boundary to reliably re-discover an installed or updated plugin (verified runtime fact — plan §3). After any `sync` that installs or reinstalls `codex-rig` or `codemap-py` itself, tell the user explicitly: "Start a new Codex session before relying on the updated plugin — this session's tool list was resolved before the update."

- ### Step 1: Resolve mode

- Parse the invocation text (case-insensitive): starts with `audit` or is empty → audit mode; `plan` → plan mode; `apply` → apply mode; `sync` → sync mode; `demo` → demo mode. Anything else → ask in chat which of the five modes was intended and wait for the reply.

- ### Step 2: Run the mode

- **`audit`** — performs a bounded read-only inspection of provider/consumer versions, observed provider content identity, managed blocks, index identity, runtime-scoped logs, usage, and findings. It reports `pass`, `warn`, or `fail` and never invokes `plan`, `apply`, `sync`, `index`, query self-heal, native plugin-manager mutation, or global-instruction installation. A same-version content mismatch is a high-severity drift finding; a native listing without session provenance is reported as `session_catalog: unobservable`. Codex contributes runtime-scoped CLI and tool shards but has no skill-start hook, and host hooks expose no token usage, so audit reports evidence limits rather than claiming live fresh-session activation or token savings. `--json` emits schema 2 (`codemap-py.integration.v2`); `--since` filters telemetry by date.

-

- **`plan`** — writes a report artifact only; no mutation. Print the artifact path, the recorded targets, and the plan SHA-256.

-

- **`apply`** — requires `--plan` and `--approve <sha256>` matching the plan just shown. Before running it, print the plan summary and SHA-256 in chat and wait for explicit approval — do not pass `--approve` on the user's behalf.

-

- **`sync`** — same approval gate as `apply`, plus `--source {local-candidate,release}`. After a successful sync, apply the Codex fresh-session instruction above when `codex-rig` or `codemap-py` was among the synced targets.

- **`demo`** — runs `audit` plus representative plain-vs-structural-context workflows and records the protocol/version/evidence used; disposable unless the user separately approves a mutation.

- ### Step 3: Report

- Print exit code meaning plainly: `0` success, `1` runtime/filesystem failure or partial-sync journal state (see the mode table), `2` bad syntax or invalid approval. On `1` during `sync`, report the journaled state (`planned → approved → applying:<t> → verified:<t> → complete`, or `rollback-started → rollback-succeeded|rollback-failed → recovery-required`) and, for `recovery-required`, the bounded manual recovery commands the engine reported — never invent recovery steps beyond what was reported.