@ahmed-g-gad/apothem 0.1.1

package/src/apothem/harnesses/codebuddy/update.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: MIT
+
+"""Update logic for the codebuddy harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_update_project
+from apothem.harnesses.codebuddy.install import install
+
+update = make_update_project(install)

package/src/apothem/harnesses/codebuddy/verify.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify logic for the codebuddy harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_verify_project
+
+_HARNESS_NAME: str = "codebuddy"
+
+verify = make_verify_project(_HARNESS_NAME)

package/src/apothem/harnesses/codex/STANDARD-CONVENTION-PIN.md

@@ -0,0 +1,79 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Codex Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification of `developers.openai.com/codex` — AGENTS.md instruction chain (`CODEX_HOME`, `AGENTS.override.md`, `project_doc_fallback_filenames`), `~/.codex/config.toml` (+ `[mcp_servers.<name>]` tables), `~/.codex/agents/*.toml` subagents, `~/.agents/skills`, `~/.codex/hooks.json`, and the first-party web-search tool all confirmed current; no authority-host move; no immutable pin — mutable docs site
+- Adapter source: `src/apothem/harnesses/codex/`
+- Evidence level: adapter-local projection; no vendor-native UI claim is made here.
+
+## MCP Surface Projection
+
+- Status: vendor-native MCP is supported via `[mcp_servers.<name>]` tables in the operator-owned `~/.codex/config.toml` (and trusted-project `.codex/config.toml`).
+- Mechanism: Apothem names this native surface in `capabilities.yml` but does not author MCP server entries; `config.toml` is operator-owned and outside the adapter's write surface.
+- Boundary: STDIO transport keys (`command`, `args`, `env`, `cwd`) and HTTP keys (`url`, `bearer_token_env_var`, `http_headers`) are vendor-defined; this pin claims only that the surface exists, not that Apothem materializes it.
+
+## Subagent and Skills Surface Projection
+
+- Subagents: standalone TOML in `~/.codex/agents/` requiring `name` / `description` / `developer_instructions`. The adapter's `codex_agents` converter emits exactly that field set (plus `model_reasoning_effort`); confirmed compliant 2026-05-31.
+- Skills: user-scope path is `~/.agents/skills` (confirmed correct). System skills are OpenAI-bundled with no official on-disk path — any `~/.codex/skills/.system` reference is an observed-runtime convenience, not an official path, and is never a write or sweep target.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Codex-facing prompts and fallback text preserve that suffix as authored.
+- Boundary: this pin does not claim a harness-native recommended-option widget. It only pins the text-rendered convention used by `rules/interactive-questions.md`.
+
+## Long Context and Compaction
+
+- Status: profile-managed.
+- Mechanism: Apothem keeps full-suite `/plan-execute` runs continuous by externalizing state to `.apothem/plans/`, compacting or restarting the harness session at phase boundaries as needed, and restoring via the Blind Bootstrap sequence.
+- Boundary: this pin does not claim vendor-native autocompaction or a long-context size. It pins the adapter-local state handoff and compaction-restoration convention used by `rules/context-management.md`.
+
+## Large-Codebase Practice Projection
+
+- Layered context: declared in `capabilities.yml` under `layered_context_surface`; no vendor-native hierarchy is claimed beyond the adapter's documented file/template surface.
+- LSP symbol navigation: `tracked-gap` until a vendor-ratified plugin or tool surface is pinned.
+- Hook learning capture: routed through the `persistent-conventions-vigilance` artifact-evolution cycle; pass-class hooks stay silent and recurring findings become rule, skill, hook, or documentation updates.
+
+## Web-Fetch / Browser-Retrieval Surface
+
+- Capability: `web_fetch` = **yes**. The backing dimension for `rules/source-accessibility.md` step 1 ("retrieve through the host's browser / fetch capability").
+- Vendor-confirmed: Codex CLI ships a first-party web search tool, enabled by default for local tasks (cache-served); `--search` or `web_search = "live"` fetches live results, `"disabled"` turns it off.
+- Evidence: vendor-doc-url <https://developers.openai.com/codex/cli/features> ("Codex ships with a first-party web search tool"); snapshot-id living docs (no immutable commit); snapshot-date 2026-06-21.
+
+## Hook Surface Projection
+
+- Status: vendor-native user-scope hooks are supported through `~/.codex/hooks.json` and may also be declared in `~/.codex/config.toml`.
+- Mechanism: Apothem installs managed hook configuration at `~/.codex/hooks.json` and helper material under `~/.codex/hooks/`.
+- Boundary: Apothem does not overwrite `~/.codex/config.toml`; operator-owned hook declarations in that file remain outside the adapter's write surface.
+
+## Plugin-alone Persistence
+
+Codex exposes a plugin-marketplace surface (`codex plugin marketplace add`).
+The bundle is `plugins/apothem/` with `.codex-plugin/plugin.json`
+(`"skills": "./skills/"`) referenced by `.agents/plugins/marketplace.json`.
+Installing the plugin *alone* — without running `apothem install` — persists
+only what the plugin package bundles; the full user-scope cohort still requires
+the engine, which converts agents to TOML and wires `~/.codex/hooks.json`.
+
+| Artifact class | Persists plugin-alone? | Mechanism / limit |
+|---|---|---|
+| Skills | Bootstrap only | The plugin bundles one skill, `skills/apothem/SKILL.md`, a launcher that instructs the operator to run `npx @ahmed-g-gad/apothem install --harness codex`. It persists and is discoverable, but it carries the *entry-point*, not the cohort. |
+| Commands | No — folded into the bootstrap skill | Codex has no separate marketplace command primitive in this bundle; the `/apothem`-equivalent entry is the bootstrap skill above. The full command cohort (command-prompt skills under `~/.agents/skills/`) lands only via `apothem install`. |
+| Context anchor (rules-as-text) | No — requires `apothem install` | `~/.codex/AGENTS.md` is written by the engine, not the plugin package. The plugin bundles no AGENTS.md, so the embedded engineering disciplines persist only after the engine run. |
+| Rules (as native primitive) | No — platform limit | Codex reserves `~/.codex/rules/` for `.rules` execution-policy files; Apothem rules are never a Codex-native rules primitive. They land as `~/.config/apothem/rules/` reference material via `apothem install`. |
+| Agents | No — requires `apothem install` | `~/.codex/agents/*.toml` is engine-converted; the plugin package bundles no agents. |
+| Hooks | No — requires `apothem install` | `~/.codex/hooks.json` + `~/.codex/hooks/` are engine-installed; the plugin package wires no hooks. |
+| MCP servers | No — operator-owned | `[mcp_servers.<name>]` tables live in operator-owned `~/.codex/config.toml`; neither the plugin nor the engine authors them. |
+
+Bundle wiring status: the plugin package persists a bootstrap launcher skill
+that runs the engine. Embedding the full converted cohort (agents-as-TOML,
+command skills, an AGENTS.md anchor carrying the engineering disciplines)
+directly into `plugins/apothem/` is a documented future enhancement — the
+conversion logic lives in the engine (`codex_agents` / `command_skills` modes
+in `propagation-manifest.yaml`), so a build step that pre-renders those into the
+bundled `plugins/apothem/` tree would let the plugin carry the cohort without a
+post-install engine run.

package/src/apothem/harnesses/codex/__init__.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for codex — raw-propagation (no materializer).
+
+Propagates the apothem convention surface into ``$CODEX_HOME`` (default
+``~/.codex/``) per the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml``.
+Per the declared divergence at ``rules/harness-adapter-shape-schemas.md`` §2
+("No materializer; …"), the codex adapter renders no standalone config file:
+the AGENTS.md anchor instead receives the shared profile as a
+sentinel-delimited Apothem managed block, preserving operator prose outside
+the sentinels.
+"""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+from typing import Any
+
+from apothem.harnesses._shared.install_driver import MaterializationRun
+from apothem.harnesses.codex.install import install as _install
+from apothem.harnesses.codex.install import plan as _plan
+from apothem.harnesses.codex.uninstall import uninstall as _uninstall
+from apothem.harnesses.codex.update import update as _update
+from apothem.harnesses.codex.verify import verify as _verify
+
+
+def _codex_home() -> Path:
+    """Return the Codex user configuration root."""
+    configured = os.environ.get("CODEX_HOME")
+    if configured:
+        return Path(configured).expanduser()
+    return Path.home() / ".codex"
+
+
+class CodexAdapter:
+    """CodexAdapter — implements :class:`~apothem.harnesses.HarnessAdapter`."""
+
+    @property
+    def name(self) -> str:
+        """Return the canonical kebab-case harness identifier."""
+        return "codex"
+
+    @property
+    def output_path(self) -> Path:
+        """Return the target configuration file path."""
+        return _codex_home() / "AGENTS.md"
+
+    def install(self, profile: dict[str, Any]) -> MaterializationRun:
+        """Materialize the harness configuration from the shared profile."""
+        return _install(self.output_path, profile)
+
+    def update(self, profile: dict[str, Any]) -> MaterializationRun:
+        """Re-materialize the harness configuration from the updated profile."""
+        return _update(self.output_path, profile)
+
+    def plan(self, output_path: Path | None = None) -> list[dict[str, str]]:
+        """Return the manifest-driven propagation plan without writing."""
+        return _plan(output_path or self.output_path)
+
+    def uninstall(self) -> None:
+        """Remove the harness configuration file if present."""
+        _uninstall(self.output_path)
+
+    def is_installed(self) -> bool:
+        """Return True if the configuration file exists on disk."""
+        return self.output_path.exists()
+
+    def verify(self) -> bool:
+        """Return True if the installed configuration is valid."""
+        return _verify(self.output_path)

package/src/apothem/harnesses/codex/capabilities.yml

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. The codex
+# harness uses AGENTS.md, hooks.json, TOML custom agents, the shared Codex
+# skills root, and an Apothem support tree for non-native Markdown cohorts.
+# MCP is natively supported via [mcp_servers.<name>] tables in the
+# operator-owned config.toml (confirmed live 2026-05-31); Apothem names
+# the native surface but does not author MCP server entries.
+
+mcp_servers:
+  - config.toml-mcp_servers-tables-operator-owned
+# Operator-owned MCP surface: the adapter recognizes it but authors no entries.
+mcp_servers_authored: false
+sub_agent_dispatch: true
+custom_command_support: "yes"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "not-documented-in-current-pin"
+layered_context_surface: "AGENTS.md plus ~/.codex/hooks.json, ~/.codex/hooks, ~/.codex/agents, ~/.agents/skills, ~/.config/apothem"
+lsp_symbol_navigation: "tracked-gap-no-adapter-owned-LSP-surface"
+hook_learning_capture: "artifact-evolution-cycle"
+standard_convention_pin: "STANDARD-CONVENTION-PIN.md"
+# web-fetch / browser-retrieval surface — the backing capability dimension for
+# rules/source-accessibility.md step 1 ("retrieve through the host's browser /
+# fetch capability"). Vendor-confirmed: Codex CLI ships a first-party web search
+# tool, enabled by default for local tasks (cache-served); `--search` or
+# `web_search = "live"` fetches live results, `"disabled"` turns it off.
+# Evidence triple — vendor-doc-url:
+# https://developers.openai.com/codex/cli/features ("Codex ships with a
+# first-party web search tool"); snapshot-id: living docs (no immutable commit);
+# snapshot-date: 2026-06-21. Canonical evidence home is STANDARD-CONVENTION-PIN.md
+# per rules/agent-capability-discipline-matrix.md §1A; pin refresh tracked as a
+# follow-up to fold this triple into the pin's evidence chain.
+web_fetch: "yes"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "n/a"
+agent_memory_surface: "AGENTS.md hierarchy"

package/src/apothem/harnesses/codex/install.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the codex harness adapter.
+
+Installs the Apothem convention surface into the OpenAI Codex CLI
+harness target. Codex CLI reads ``$CODEX_HOME/AGENTS.md`` as the
+vendor-canonical agent-instructions file and discovers lifecycle hooks
+from ``$CODEX_HOME/hooks.json`` plus hook helpers under
+``$CODEX_HOME/hooks/``. Agents are converted to
+``$CODEX_HOME/agents/*.toml``. Skills and command prompts propagate to the
+shared Codex skills root ``~/.agents/skills/``. Markdown rules and templates
+live under ``~/.config/apothem/`` as support material because Codex reserves
+``$CODEX_HOME/rules/`` for ``.rules`` execution-policy files.
+
+Codex runtime configuration lives at ``$CODEX_HOME/config.toml`` and is
+operator-owned; this adapter does not overwrite that file.
+
+The adapter is user-scope: it propagates under the harness root resolved
+as ``output_path.parent`` (``~/.codex/``). Its propagation contract is
+declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``codex`` key
+and applied by the shared driver at
+``apothem.harnesses._shared.install_driver``. Drift between the
+propagation contract and the on-disk install is impossible by
+construction: the manifest IS the contract.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+
+from apothem.harnesses._shared import install_driver
+from apothem.harnesses._shared.install_driver import MaterializationRun
+
+# Manifest harness key for this adapter.
+_HARNESS_NAME: str = "codex"
+
+
+def install(output_path: Path, profile: dict[str, Any]) -> MaterializationRun:
+    """Install the apothem convention surface into the Codex CLI harness.
+
+    The harness root is derived as ``output_path.parent`` — the
+    ``CodexAdapter`` resolves this to ``$CODEX_HOME``. The shared ``profile``
+    is projected into the ``AGENTS.md`` instruction anchor as a
+    sentinel-delimited Apothem managed block (operator prose outside the
+    sentinels is preserved); the convention cohorts (skills, agents-as-TOML,
+    hooks) propagate alongside it. All operations are idempotent —
+    re-running replaces previous content cleanly, eliminating stale files
+    from prior install layouts.
+    """
+    return install_driver.finalize_install(
+        install_driver.run_install(
+            _HARNESS_NAME, harness_root=output_path.parent, profile=profile
+        ),
+        root=output_path.parent,
+    )
+
+
+def plan(output_path: Path) -> list[dict[str, str]]:
+    """Return the propagation plan for the configured harness without writing.
+
+    Each entry carries ``source`` (resolved on-disk path), ``target``
+    (resolved absolute path under ``output_path.parent``), and ``mode``
+    (``write_text``, a tree mode, or a conversion mode). The plan is the manifest's
+    install list materialized against the active harness root — the same
+    sequence ``install`` would apply, in declaration order.
+    """
+    return install_driver.build_plan(_HARNESS_NAME, harness_root=output_path.parent)

package/src/apothem/harnesses/codex/templates/AGENTS.md

@@ -0,0 +1,40 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Codex Bootstrap
+
+This file is the vendor-canonical agent-instructions surface for the
+OpenAI Codex CLI (`$CODEX_HOME/AGENTS.md`, default `~/.codex/AGENTS.md`).
+It follows the universal AGENTS.md convention adopted across coding-agent
+ecosystems. Apothem's governance surface is split between Codex-native
+discovery paths and an Apothem-owned support tree for content that is not a
+Codex-native primitive.
+
+## Apothem Conventions
+
+The Apothem-managed cohorts are installed as follows:
+
+- `$CODEX_HOME/agents/*.toml` — Codex custom agents converted from Apothem
+  Markdown agents.
+- `$CODEX_HOME/hooks.json` and `$CODEX_HOME/hooks/` — Codex lifecycle hook
+  configuration plus Apothem hook helpers.
+- `~/.agents/skills/*/SKILL.md` — Apothem skills plus command prompts wrapped
+  as Codex skills.
+- `~/.config/apothem/rules/` — Apothem Markdown rules used as reference
+  material by this file and the installed skills.
+- `~/.config/apothem/templates/` — plan, report, and audit templates.
+
+Do not place Apothem Markdown rules under `$CODEX_HOME/rules/`. Codex
+reserves that directory for `.rules` execution-policy files, which use a
+different format and purpose.
+
+## Runtime Configuration
+
+Codex CLI's runtime configuration lives at `$CODEX_HOME/config.toml`. Apothem
+does not overwrite that operator-owned file; it installs instructions, hooks,
+agents, skills, and support content through the vendor-native paths above.
+
+## Operator Surface
+
+Operators may extend project-specific instructions in project-local
+`AGENTS.md` files. Re-run `apothem install --harness codex` to refresh this
+user-scope bootstrap, converted agents, skills, and support cohorts.

package/src/apothem/harnesses/codex/templates/hooks.json

@@ -0,0 +1,127 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "matcher": "startup|resume|clear|compact",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" SessionStart",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" SessionStart",
+            "timeout": 30,
+            "statusMessage": "Initializing session posture"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-bash",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-bash",
+            "timeout": 10,
+            "statusMessage": "Validating shell command safety and isolation"
+          },
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-bash-plan-guard",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-bash-plan-guard",
+            "timeout": 10,
+            "statusMessage": "Enforcing plans locality on shell redirections"
+          },
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-eval-guard",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-eval-guard",
+            "timeout": 10,
+            "statusMessage": "Flagging unsafe dynamic evaluation or deserialization"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write|apply_patch",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-write",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-write",
+            "timeout": 10,
+            "statusMessage": "Validating write target and content"
+          },
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-write-header-guard",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-write-header-guard",
+            "timeout": 10,
+            "statusMessage": "Injecting authorship header if missing"
+          },
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-write-plan-guard",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-write-plan-guard",
+            "timeout": 10,
+            "statusMessage": "Enforcing plans locality on the target path"
+          },
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-dependency-guard",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-dependency-guard",
+            "timeout": 10,
+            "statusMessage": "Flagging unpinned or untrusted dependency additions"
+          },
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-eval-guard",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreToolUse pretooluse-eval-guard",
+            "timeout": 10,
+            "statusMessage": "Flagging unsafe dynamic evaluation or deserialization"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "matcher": "manual|auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreCompact precompact",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PreCompact precompact",
+            "timeout": 30,
+            "statusMessage": "Externalizing state before context compression"
+          }
+        ]
+      }
+    ],
+    "PostCompact": [
+      {
+        "matcher": "manual|auto",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PostCompact postcompact",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" PostCompact postcompact",
+            "timeout": 30,
+            "statusMessage": "Restoring state from durable files after compaction"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${HARNESS_ROOT}/hooks/dispatch.py\" Stop stop",
+            "commandWindows": "py -3 \"${HARNESS_ROOT}/hooks/dispatch.py\" Stop stop",
+            "timeout": 60,
+            "statusMessage": "Finalizing session and externalizing state"
+          }
+        ]
+      }
+    ]
+  }
+}

package/src/apothem/harnesses/codex/uninstall.py

@@ -0,0 +1,23 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the codex harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+
+_HARNESS_NAME: str = "codex"
+
+
+def uninstall(output_path: Path) -> None:
+    """Remove Apothem-managed Codex targets surgically.
+
+    AGENTS.md is a ``sentinel_merge`` anchor and hooks.json an operator-owned
+    ``write_text`` JSON target, so the shared driver strips only Apothem's
+    managed block / keys / hook handlers (operator prose and operator keys
+    survive) and backs each file up under the Apothem backup root — no whole-file
+    ``.bak`` sibling is left beside the operator's files.
+    """
+    install_driver.run_uninstall(_HARNESS_NAME, harness_root=output_path.parent)

package/src/apothem/harnesses/codex/update.py

@@ -0,0 +1,10 @@
+# SPDX-License-Identifier: MIT
+
+"""Update logic for the codex harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_update
+from apothem.harnesses.codex.install import install
+
+update = make_update(install)

package/src/apothem/harnesses/codex/verify.py

@@ -0,0 +1,11 @@
+# SPDX-License-Identifier: MIT
+
+"""Verify logic for the codex harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_verify_harness_root
+
+_HARNESS_NAME: str = "codex"
+
+verify = make_verify_harness_root(_HARNESS_NAME)

package/src/apothem/harnesses/cursor/STANDARD-CONVENTION-PIN.md

@@ -0,0 +1,79 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Cursor Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification against `cursor.com/docs/context/rules` — the `.cursor/rules/*.mdc` rules surface, the frontmatter fields (`description` / `globs` / `alwaysApply`), and the `docs.cursor.com`→`cursor.com/docs` host move all confirmed current.
+- Adapter source: `src/apothem/harnesses/cursor/`
+- Evidence level: adapter-local projection; no vendor-native UI claim is made here.
+
+## Official Surface Refresh
+
+- Refreshed live 2026-05-31 against the current Cursor documentation. The
+  authority host moved: `docs.cursor.com` now 308-redirects to `cursor.com/docs`.
+  No immutable version pin is exposed (mutable docs site), so every captured
+  convention carries a no-immutable-source exception.
+- Confirmed live: rules surface `.cursor/rules/*.mdc` (frontmatter
+  `description`/`globs`/`alwaysApply`); MCP via `~/.cursor/mcp.json` plus
+  `.cursor/mcp.json` (operator-owned; the adapter recognizes it but does not
+  author entries).
+- The vendor now documents a plugin mechanism (`.cursor-plugin/plugin.json`)
+  that can bundle agents, commands, skills, and hooks. The adapter delivers only
+  the project rules file (`apothem-rules.mdc`) and authors none of those cohorts;
+  this rules-only posture is deliberate and the plugin-bundle delivery question
+  is a propagation write-planning concern, not part of this adapter.
+- Settings (IDE-managed) and status-lines remain undocumented as file surfaces.
+
+## Web-Fetch / Browser-Retrieval Surface
+
+- Capability: `web_fetch` = **partial**. The backing dimension for
+  `rules/source-accessibility.md` step 1 ("retrieve through the host's browser /
+  fetch capability").
+- Vendor-confirmed PARTIAL: Cursor exposes `@Web` — a user-invoked
+  context-injection web search ("performs a live web search to retrieve
+  up-to-date information"), plus an "Always search the web" auto setting. It is a
+  context-injection symbol rather than a documented autonomous agent-loop fetch
+  tool, hence the `partial` subset boundary (user-invoked search yes; autonomous
+  fetch tool not documented).
+- Evidence: vendor-doc-url <https://docs.cursor.com/context/@-symbols/@-web>;
+  snapshot-id living docs; snapshot-date 2026-06-21.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Cursor rule templates preserve that suffix as authored.
+- Boundary: this pin does not claim a harness-native recommended-option widget. It only pins the text-rendered convention used by `rules/interactive-questions.md`.
+
+## Long Context and Compaction
+
+- Status: profile-managed.
+- Mechanism: Apothem keeps full-suite `/plan-execute` runs continuous by externalizing state to `.apothem/plans/`, compacting or restarting the harness session at phase boundaries as needed, and restoring via the Blind Bootstrap sequence.
+- Boundary: this pin does not claim vendor-native autocompaction or a long-context size. It pins the adapter-local state handoff and compaction-restoration convention used by `rules/context-management.md`.
+
+## Large-Codebase Practice Projection
+
+- Layered context: declared in `capabilities.yml` under `layered_context_surface`; no vendor-native hierarchy is claimed beyond the adapter's documented file/template surface.
+- LSP symbol navigation: `tracked-gap` until a vendor-ratified plugin or tool surface is pinned.
+- Hook learning capture: routed through the `persistent-conventions-vigilance` artifact-evolution cycle; pass-class hooks stay silent and recurring findings become rule, skill, hook, or documentation updates.
+
+## Plugin-alone Persistence
+
+Cursor documents a vendor plugin mechanism (`.cursor-plugin/plugin.json` that can
+bundle agents, commands, skills, and hooks), but **Apothem ships no Cursor
+plugin bundle** — the adapter is project-scope rules-only, writing a single
+merged MDC rules file at `<project>/.cursor/rules/apothem-rules.mdc` and authoring
+no other cohort. There is no Apothem-distributable standalone bundle; every
+artifact requires the full `apothem install --harness cursor --project <path>`
+engine run.
+
+| Artifact class | Persists standalone? | Mechanism / limit |
+|---|---|---|
+| Rules | No — requires `apothem install` | The merged `apothem-rules.mdc` (carrying the embedded behavioral mandates) is written only by the engine into the vendor-native `.cursor/rules/` directory. Nothing persists before that run. |
+| Commands / Skills / Agents / Hooks | No — Apothem ships no bundle | Cursor's `.cursor-plugin/plugin.json` accepts these cohorts, but Apothem authors no Cursor plugin; the rules-only posture is deliberate. Bundling the cohort into a Cursor plugin is a documented future propagation-write-planning concern, not part of this adapter today. |
+| MCP / Settings | No — operator-owned | `~/.cursor/mcp.json` / `.cursor/mcp.json` and IDE-managed settings are operator-owned; the adapter authors no entries. |
+
+Platform note: the vendor plugin surface exists; the Apothem-distributable
+plugin bundle does not yet. The merged rules file via `apothem install` is the
+sole persistence surface for now.

package/src/apothem/harnesses/cursor/__init__.py

@@ -0,0 +1,48 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for cursor — project-scope install.
+
+Materializes the apothem rules surface into the operator-supplied
+project root at ``<project>/.cursor/rules/apothem-rules.mdc`` — the
+canonical Cursor rules surface per
+https://cursor.com/docs/context/rules. The legacy single-file
+``~/.cursorrules`` user-scope target is excluded because Apothem targets the
+current project rules surface; Cursor does not offer a file-based user-global
+rules surface.
+
+The adapter opts into the project-scope contract via
+``requires_project = True``; the CLI rejects an install / update /
+uninstall / verify invocation that omits ``--project <path>``. Delegates
+install logic to :mod:`apothem.harnesses.cursor.install`, which consumes
+the canonical propagation manifest at
+``src/apothem/lib/propagation-manifest.yaml``.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared.wrapper_factories import make_project_scope_adapter
+from apothem.harnesses.cursor.install import install as _install
+from apothem.harnesses.cursor.install import plan as _plan
+from apothem.harnesses.cursor.uninstall import uninstall as _uninstall
+from apothem.harnesses.cursor.update import update as _update
+from apothem.harnesses.cursor.verify import verify as _verify
+
+# Sentinel relative path used by ``output_path`` for display purposes
+# only. The real target is resolved per-install via
+# ``resolve_output_path(project)`` once the operator supplies
+# ``--project <path>``.
+_SENTINEL_RELATIVE: Path = Path(".cursor") / "rules" / "apothem-rules.mdc"
+
+CursorAdapter = make_project_scope_adapter(
+    "cursor",
+    error_label="cursor",
+    relative_target=_SENTINEL_RELATIVE,
+    install_fn=_install,
+    plan_fn=_plan,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="CursorAdapter",
+)