@ahmed-g-gad/apothem 0.1.1

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

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7 and the matrix
+# companion §3. Cursor ratifies MCP via ~/.cursor/mcp.json (user-scope)
+# plus project-level .cursor/mcp.json; rules surface as MDC files under
+# .cursor/rules/. The adapter delivers a single project rules file and
+# does not dispatch sub-agents or author command/skill/hook cohorts;
+# the Cursor plugin mechanism that could host those is operator-driven.
+
+mcp_servers:
+  - user-scope-~/.cursor/mcp.json
+  - project-scope-.cursor/mcp.json
+# Operator-owned MCP surface: the adapter recognizes it but authors no entries.
+mcp_servers_authored: false
+sub_agent_dispatch: false
+custom_command_support: "no"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "not-documented-in-current-pin"
+layered_context_surface: ".cursor/rules MDC files"
+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 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 triple — vendor-doc-url:
+# https://docs.cursor.com/context/@-symbols/@-web; snapshot-id: living docs;
+# 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.
+web_fetch: "partial"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "templates/apothem-rules.mdc"
+agent_memory_surface: "n/a"

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

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the cursor harness adapter.
+
+Materializes the apothem Cursor rules surface into the operator-supplied
+project root. Cursor's canonical user-facing rules surface is the
+project-scope MDC ruleset at ``<project>/.cursor/rules/*.mdc`` (per
+https://cursor.com/docs/context/rules). The legacy single-file
+``~/.cursorrules`` target is excluded because Apothem targets the current
+multi-file project rules surface.
+
+The propagation contract is declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``cursor`` key
+(a single ``sentinel_merge`` operation targeting
+``${PROJECT_ROOT}/.cursor/rules/apothem-rules.mdc``) and applied by the
+shared driver at ``apothem.harnesses._shared.install_driver``. The
+``${PROJECT_ROOT}`` placeholder is substituted with the operator-supplied
+``--project <path>`` value the CLI threads through; absence of
+``--project`` is rejected upstream at ``apothem.cli._materialize`` via the
+``requires_project`` opt-in.
+"""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import (
+    make_project_scope_install,
+    make_project_scope_plan,
+)
+
+# Manifest harness key for this adapter.
+_HARNESS_NAME: str = "cursor"
+
+install = make_project_scope_install(
+    _HARNESS_NAME,
+    error_message="cursor adapter requires --project <path>; CLI must thread it through",
+)
+
+plan = make_project_scope_plan(_HARNESS_NAME)

package/src/apothem/harnesses/cursor/templates/apothem-rules.mdc

@@ -0,0 +1,40 @@
+---
+description: "Apothem governance and convention surface for the Cursor harness — read every session to honour project-wide engineering discipline."
+globs: "**/*"
+alwaysApply: true
+---
+
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Cursor Bootstrap
+
+This file is materialised by `apothem install --harness cursor --project <path>` and lands at `<project>/.cursor/rules/apothem-rules.mdc`, the current Cursor project rules surface per https://cursor.com/docs/context/rules. The legacy single-file `.cursorrules` target is excluded because Apothem targets the multi-file project rules format; this MDC file is the authoritative Cursor-facing anchor.
+
+## What Apothem governs in this project
+
+Apothem propagates a shared governance and convention surface across every supported AI harness in this project's host environment. Inside Cursor, the surface manifests as:
+
+- **Rules** — always-on and path-filtered engineering rules. The full rule cohort lives at the apothem source repository under `src/apothem/rules/`; that cohort is the authoritative source. This MDC file is the Cursor-facing anchor; consult the apothem rules tree (or this project's mirrored documentation) for the per-rule body.
+- **Skills, commands, agents** — reusable techniques, slash-style workflows, and persistent sub-agent definitions. Apothem's canonical-master cohort at the apothem source repository defines them; their per-harness reachability depends on Cursor's discovery contract.
+- **Conformity matchers** — mechanical pre-emission checks that gate artifact emission. The apothem package installs them as the `apothem-conformity` console-script entry point and as PreToolUse hooks where the harness supports hooks.
+
+## Engineering disciplines in force
+
+Apothem's foundational mandates apply uniformly across every harness, including Cursor:
+
+- **Plans-Locality.** Plan-suite artefacts (PROGRESS.md, PLAN-NOTES.md, PHASE.md, REPORT.md) live under `<project>/.apothem/plans/{suite}/` — the sole canonical home; a legacy `<project>/.plans/` tree upgrades via `apothem migrate-workspace`. They never land in a global plans directory or any other global-ecosystem location.
+- **Authority hygiene.** Never fabricate identity, scope, security posture, or version-pin data. Surface ambiguity via the canonical structured-inquiry channel; the operator chooses.
+- **Definitiveness.** Hedging vocabulary (`maybe`, `might`, `usually`, `generally`, `typically`, `probably`) is eliminated where binding prescription is possible. Pre / post / failure conditions are stated on every contract.
+- **Production-ready discipline.** Every change ships in production-ready form — tests, docs, CHANGELOG entry, conformant commit message, CI green — in the same change-set.
+- **Plain-language.** Codebase artefacts and user-facing prose read as natural domain language with zero trace of internal planning structure.
+- **Lean-context delegation.** Where the host provides delegated-worker dispatch, broad reads and heavy workloads route to a spawned worker by default so the main working context stays lean. The heavy parallel apparatus stays opt-in; routing delegable work away from the main thread is the standing posture once dispatch is available.
+- **Observe-decide-act discipline.** Tool use runs as a loop — observe the current state, decide the next move from what was observed, then act — never an edit before a read or a result asserted before a check. Independent reads and searches run together in one pass, not one per turn; the loop closes on a verifiable condition (a gate green, a read confirmed), never a fixed number of tries. Advisory, never an auto-applied behavior.
+- **Source accessibility.** When the authoritative source for a claim, convention, or version pin is closed, paywalled, login-gated, or otherwise unreachable, ask the operator for it in full rather than substituting a lower-trust open page. Trust outranks reachability.
+
+## How to use this file
+
+Cursor reads this MDC file at every session start because `alwaysApply: true` forces inclusion regardless of file-context heuristics. The `globs: "**/*"` field declares the rule applies project-wide. The body above is the high-density summary; the apothem rule cohort at the apothem source repository carries the full per-rule specifications.
+
+## Refreshing the file
+
+Re-run `apothem install --harness cursor --project <this-project-root>` to overwrite the file with the latest apothem template. The operation is idempotent — re-running cleanly replaces the prior content. The companion `apothem uninstall --harness cursor --project <this-project-root>` removes the file with a timestamped backup. The `apothem verify --harness cursor --project <this-project-root>` command checks the file is present and non-empty.

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

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the cursor harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+
+_HARNESS_NAME: str = "cursor"
+
+
+def uninstall(output_path: Path, *, project: Path | None = None) -> None:
+    """Remove Apothem-managed Cursor targets surgically.
+
+    The apothem-rules ``sentinel_merge`` anchor is cleaned by the shared driver,
+    which strips only Apothem's managed block (operator prose survives), deletes
+    an Apothem-only file, and backs the file up under the Apothem backup root —
+    no whole-file ``.bak`` sibling is left beside the operator's file.
+    """
+    install_driver.run_uninstall(
+        _HARNESS_NAME,
+        project_root=project or output_path.parents[2],
+    )

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

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

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

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

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

@@ -0,0 +1,102 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Gemini CLI Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification against `github.com/google-gemini/gemini-cli` docs — hierarchical `GEMINI.md` context (`@file.md` imports), TOML custom commands (`~/.gemini/commands/*.toml`, required `prompt`), and built-in `web_fetch` / `google_web_search` all confirmed current; previous live-fetch 2026-06-21 / 2026-05-22
+- Adapter source: `src/apothem/harnesses/gemini_cli/`.
+- Upstream authority: `github.com/google-gemini/gemini-cli`, release `v0.44.1`
+  (2026-05-28), main HEAD commit `013914071c5412188661014f2670ce3818cb98c3`
+  (2026-05-29) — an immutable pin (one of the three GitHub-backed harnesses).
+- Evidence level: official-source-backed for the surfaces below; no vendor-native UI claim is made here.
+- Lifecycle: Google deprecates the standalone Gemini CLI for the AI Pro / AI
+  Ultra and free individual tiers on 2026-06-18, consolidating its developer
+  tooling under Antigravity CLI (binary `agy`; see the sibling `antigravity`
+  adapter and its pin, which materializes the successor). Gemini Code Assist
+  Standard / Enterprise and paid API keys keep the legacy CLI working, so this
+  adapter stays valid for those accounts; individual-tier users route to the
+  `antigravity` harness. Primary source: Google Developers Blog "Transitioning
+  Gemini CLI to Antigravity CLI" (I/O, 2026-05-19).
+
+## Native Surfaces (live-confirmed 2026-05-31)
+
+- Project context anchor: `<project>/GEMINI.md` (and global `~/.gemini/GEMINI.md`);
+  the user-scope `~/.gemini/` tree is reserved for the antigravity adapter, so
+  this project-scope adapter materializes under `<project>/` exclusively.
+- MCP: the `mcpServers` object in the operator-owned `settings.json` (user
+  `~/.gemini/settings.json`, project `.gemini/settings.json`). It supports stdio
+  (`command`/`args`) and HTTP (`url` for SSE, `httpUrl` for streamable). Apothem
+  names this surface but does not author MCP server entries; `settings.json` is
+  operator-owned and never written by the adapter.
+- Hooks: a native `hooks` object in `settings.json` with per-event arrays and a
+  `matcher`, spanning eleven lifecycle events (SessionStart, SessionEnd,
+  BeforeAgent, AfterAgent, BeforeModel, AfterModel, BeforeToolSelection,
+  BeforeTool, AfterTool, PreCompress, Notification). Apothem keeps its hook
+  message-context prose as support material under `<project>/.gemini/apothem/`
+  and does not register native settings.json hooks (the operator owns
+  `settings.json`).
+- Skills: four-tier discovery (built-in, extension, user `~/.gemini/skills/`,
+  workspace `.gemini/skills/`), each with an `~/.agents/skills/` / `.agents/skills/`
+  alias; `SKILL.md` entry. Apothem installs to the native `<project>/.gemini/skills/`.
+- Commands: TOML custom commands (`.toml`, required `prompt`, optional
+  `description`) under `~/.gemini/commands/` (user) / `.gemini/commands/`
+  (project). Apothem converts its command cohort to this native TOML shape.
+- Memory: the Auto Memory feature scans transcripts and writes candidate diffs
+  plus skill drafts to a review inbox (`/memory inbox`), with durable memory
+  stored in `GEMINI.md`. There is no `.gemini/memory/` directory; the adapter's
+  memory surface is the GEMINI.md context anchor.
+- Web-fetch / browser-retrieval (`web_fetch` = **yes**): gemini-cli ships
+  built-in `web_fetch` and `google_web_search` tools — the backing dimension for
+  `rules/source-accessibility.md` step 1. Evidence: vendor-doc commit-pinned to
+  the same immutable snapshot as this adapter's pin (the `Upstream authority`
+  commit-sha above, `013914071c5412...`) at the repo-relative docs paths
+  `docs/tools/web-fetch.md` (+ `docs/tools/web-search.md`) under
+  `github.com/google-gemini/gemini-cli`; snapshot-date 2026-06-21.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Gemini CLI-facing 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
+
+Gemini CLI exposes a vendor extension surface (`gemini extensions install`). The
+repo root IS the extension root: `gemini-extension.json` (manifest), `GEMINI.md`
+(the manifest's `contextFileName` anchor), and a sibling `commands/apothem.toml`
+the harness auto-discovers. Installing the extension *alone* — without running
+`apothem install` — persists only what the vendor extension surface carries; the
+full per-project cohort still requires the engine, which converts each Apothem
+artifact to its Gemini-native shape.
+
+| Artifact class | Persists extension-alone? | Mechanism / limit |
+|---|---|---|
+| Context anchor (rules-as-text) | Yes | `GEMINI.md` is loaded as session context by `contextFileName`; it now embeds the core engineering disciplines (Plans-Locality, Authority hygiene, Definitiveness, Production-ready, Plain-language) so those directives persist as context text. |
+| Commands | Bootstrap only | The bundled `/apothem` command (`commands/apothem.toml`) auto-discovers and persists; it shells `npx @ahmed-g-gad/apothem`. The full converted command cohort (`.gemini/commands/*.toml`) requires `apothem install`. |
+| Skills | No — requires `apothem install` | The extension manifest bundles no skills; `.gemini/skills/*/SKILL.md` lands only via the engine. |
+| Rules (as native primitive) | No — platform limit | Gemini CLI has no native rules-directory primitive; Apothem rules persist as the `GEMINI.md` context text above, or as the engine-installed `.gemini/apothem/rules/` reference tree. |
+| Hooks | No — platform limit | Native `settings.json` hooks are operator-owned; Apothem does not register them. Hook support material lands only via `apothem install` under `.gemini/apothem/hooks/`. |
+| MCP servers | No — operator-owned | `mcpServers` lives in operator-owned `settings.json`; neither the extension manifest nor the engine authors MCP entries. |
+| Tools / settings | No — operator-owned | `settings.json` is operator-owned and never written by the adapter or the extension. |
+
+Bundle wiring status: the extension bundle persists the context anchor + the
+`/apothem` bootstrap command. Embedding the full converted command, skill, and
+agent cohort into the extension package is a documented future enhancement —
+the conversion logic lives in the engine (`gemini_commands` / `gemini_agents`
+modes in `propagation-manifest.yaml`), so a build step that pre-renders those
+into a bundled `commands/` + `.gemini/` tree would let the extension carry the
+cohort without a post-install engine run.

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

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for gemini-cli — project-scope install.
+
+Materializes the apothem rules + convention cohort into the operator-
+supplied project root at ``<project>/GEMINI.md`` (vendor-canonical
+project-context anchor) plus
+``<project>/.gemini/{commands,skills,agents,apothem}/`` per the
+gemini-cli configuration discovery contract at
+https://google-gemini.github.io/gemini-cli/docs/.
+
+The gemini-cli adapter is project-scope only: user-scope ``~/.gemini/``
+is reserved for the antigravity adapter, which owns
+``~/.gemini/GEMINI.md`` as its anchor. The gemini-cli adapter avoids the
+shared namespace by materialising under ``<project>/`` exclusively.
+
+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.gemini_cli.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.gemini_cli.install import install as _install
+from apothem.harnesses.gemini_cli.install import plan as _plan
+from apothem.harnesses.gemini_cli.uninstall import uninstall as _uninstall
+from apothem.harnesses.gemini_cli.update import update as _update
+from apothem.harnesses.gemini_cli.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("GEMINI.md")
+
+GeminiCliAdapter = make_project_scope_adapter(
+    "gemini-cli",
+    error_label="gemini_cli",
+    relative_target=_SENTINEL_RELATIVE,
+    install_fn=_install,
+    plan_fn=_plan,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="GeminiCliAdapter",
+)

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

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. The gemini_cli
+# harness anchors project-scope GEMINI.md plus native .gemini/{commands,
+# skills,agents}/ surfaces and .gemini/apothem/ support cohorts. MCP is
+# natively supported via the mcpServers object in the operator-owned
+# settings.json (confirmed live 2026-05-31); Apothem names the native
+# surface but does not author MCP server entries. A native settings.json
+# hooks surface (eleven lifecycle events) is documented in the convention
+# pin; Apothem keeps hook prose as support material and does not register
+# native settings.json hooks.
+
+mcp_servers:
+  - settings.json-mcpServers-stdio-and-http-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: "GEMINI.md plus .gemini native dirs and .gemini/apothem support"
+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: gemini-cli ships built-in `web_fetch`
+# and `google_web_search` tools. Evidence triple — vendor-doc-url (commit-pinned
+# to the same immutable snapshot as this adapter's pin):
+# https://github.com/google-gemini/gemini-cli/blob/013914071c5412188661014f2670ce3818cb98c3/docs/tools/web-fetch.md
+# (+ .../docs/tools/web-search.md); commit-sha:
+# 013914071c5412188661014f2670ce3818cb98c3; 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 add the web-fetch tool row to the pin's "Native Surfaces" block.
+web_fetch: "yes"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "templates/GEMINI.md"
+agent_memory_surface: "GEMINI.md context files via the Auto Memory inbox (no dedicated memory directory)"

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

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the gemini-cli harness adapter.
+
+Materializes the apothem convention surface into the operator-supplied
+project root. The gemini-cli adapter is project-scope only: user-scope
+``~/.gemini/`` is reserved for the antigravity adapter, which owns
+``~/.gemini/GEMINI.md``. The gemini-cli adapter avoids the shared
+namespace by materialising under ``<project>/`` exclusively.
+
+Vendor-canonical project-context surface is ``<project>/GEMINI.md``
+(analogous to project CLAUDE.md per
+https://github.com/google-gemini/gemini-cli/blob/main/docs/reference/configuration.md
+commit 792654c). The apothem convention cohort propagates under
+``<project>/.gemini/{commands,skills,agents}/`` plus
+``<project>/.gemini/apothem/`` for Markdown rules, templates, and hook
+support material that Gemini CLI does not expose as a matching native
+primitive.
+
+The propagation contract is declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``gemini_cli``
+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 apothem.harnesses._shared.wrapper_factories import (
+    make_project_scope_install,
+    make_project_scope_plan,
+)
+
+# Manifest harness key for this adapter.
+_HARNESS_NAME: str = "gemini_cli"
+
+install = make_project_scope_install(
+    _HARNESS_NAME,
+    error_message="gemini_cli adapter requires --project <path>; CLI must thread it through",
+)
+
+plan = make_project_scope_plan(_HARNESS_NAME)

package/src/apothem/harnesses/gemini_cli/templates/GEMINI.md

@@ -0,0 +1,38 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Gemini CLI Bootstrap
+
+This file is materialised by `apothem install --harness gemini-cli --project <path>` and lands at `<project>/GEMINI.md`, the vendor-canonical project-context surface. Analogous to the project `CLAUDE.md` anchor, this file is read by `gemini-cli` at every session start in this project.
+
+The gemini-cli adapter is project-scope only. User-scope `~/.gemini/` is already claimed by the antigravity adapter (which writes `~/.gemini/GEMINI.md` as its anchor); the gemini-cli adapter sidesteps the namespace collision by materialising under `<project>/` exclusively.
+
+## What Apothem governs in this project
+
+Apothem propagates a shared governance and convention surface across every supported AI harness in this project's host environment. Inside `gemini-cli`, the surface manifests at the project root as native Gemini files plus an Apothem support tree:
+
+- `<project>/GEMINI.md` — this file; the vendor-discovered project-context anchor.
+- `<project>/.gemini/commands/*.toml` — Gemini slash commands converted from Apothem command prompts.
+- `<project>/.gemini/agents/*.md` — local Gemini subagents normalized from Apothem agents.
+- `<project>/.gemini/skills/*/SKILL.md` — Apothem skills where a skill surface is available.
+- `<project>/.gemini/apothem/rules/` — Apothem Markdown rules used as reference material.
+- `<project>/.gemini/apothem/templates/` — plan, report, and audit templates.
+- `<project>/.gemini/apothem/hooks/` — hook messages and helper scripts retained as support material.
+
+Do not treat `.gemini/apothem/` as a Gemini-native discovery namespace. It is
+an Apothem-owned support tree referenced by this bootstrap, generated commands,
+and installed skills.
+
+## Engineering disciplines in force
+
+Apothem's foundational mandates apply uniformly across every harness, including gemini-cli:
+
+- **Plans-Locality.** Plan-suite artefacts (PROGRESS.md, PLAN-NOTES.md, PHASE.md, REPORT.md) live under `<project>/.apothem/plans/{suite}/` — the sole canonical home; a legacy `<project>/.plans/` tree upgrades via `apothem migrate-workspace`. They never land in a global plans directory or any other global-ecosystem location.
+- **Authority hygiene.** Never fabricate identity, scope, security posture, or version-pin data. Surface ambiguity via the canonical structured-inquiry channel; the operator chooses.
+- **Definitiveness.** Hedging vocabulary (`maybe`, `might`, `usually`, `generally`, `typically`, `probably`) is eliminated where binding prescription is possible. Pre / post / failure conditions are stated on every contract.
+- **Production-ready discipline.** Every change ships in production-ready form — tests, docs, CHANGELOG entry, conformant commit message, CI green — in the same change-set.
+- **Plain-language.** Codebase artefacts and user-facing prose read as natural domain language with zero trace of internal planning structure.
+- **Observe-decide-act discipline.** Tool use runs as a loop — observe the current state, decide the next move from what was observed, then act — never an edit before a read or a result asserted before a check. Independent reads and searches run together in one pass, not one per turn; the loop closes on a verifiable condition (a gate green, a read confirmed), never a fixed number of tries. Advisory, never an auto-applied behavior.
+
+## Refreshing the file
+
+Re-run `apothem install --harness gemini-cli --project <this-project-root>` to refresh this file, converted native entries, and support cohorts. The operation is idempotent and replaces Apothem-managed child entries while preserving unrelated operator files. The companion `apothem uninstall --harness gemini-cli --project <this-project-root>` renames the file to a timestamped backup; `apothem verify --harness gemini-cli --project <this-project-root>` checks the file is present and non-empty.

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

@@ -0,0 +1,25 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the gemini-cli harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+
+_HARNESS_NAME: str = "gemini_cli"
+
+
+def uninstall(output_path: Path, *, project: Path | None = None) -> None:
+    """Remove Apothem-managed Gemini CLI targets surgically.
+
+    The GEMINI.md ``sentinel_merge`` anchor is cleaned by the shared driver,
+    which strips only Apothem's managed block (operator prose survives), deletes
+    an Apothem-only file, and backs the file up under the Apothem backup root —
+    no whole-file ``.bak`` sibling is left beside the operator's file.
+    """
+    install_driver.run_uninstall(
+        _HARNESS_NAME,
+        project_root=project or output_path.parent,
+    )

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

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

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

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

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

@@ -0,0 +1,84 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# GitHub Copilot Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification against `docs.github.com` — `.github/copilot-instructions.md` (repo-wide) + `*.instructions.md` (path-specific `applyTo`, both-used-together) + the Copilot CLI `web_fetch` tool all confirmed current.
+- Adapter source: `src/apothem/harnesses/github_copilot/`
+- Evidence level: adapter-local projection; no vendor-native UI claim is made here.
+
+## Official Surface Refresh
+
+- Refreshed live 2026-05-31 against the current GitHub Copilot documentation
+  (`docs.github.com`). No authority-host move; no immutable version pin is
+  exposed (mutable docs site), so every captured convention carries a
+  no-immutable-source exception.
+- Instruction surface is broader than the single repo-wide file: the vendor
+  recognizes `.github/copilot-instructions.md` (repo-wide),
+  `.github/instructions/*.instructions.md` (`applyTo` glob, optional
+  `excludeAgent`), `AGENTS.md` (nearest-in-tree wins), and root `CLAUDE.md` /
+  `GEMINI.md`. The adapter delivers only the repo-wide
+  `.github/copilot-instructions.md`; the other anchors are operator-owned and
+  read-only.
+- The vendor now documents skills (`.github/skills/<name>/SKILL.md`), hooks
+  (`.github/hooks/*.json`), and CLI plugins (`plugin.json`). The adapter delivers
+  only the instructions file and authors none of those cohorts (deliberate
+  preserve-first posture).
+- MCP is service / IDE state (`~/.copilot/mcp-config.json`), not a repo-writable
+  file, so `capabilities.yml` `mcp_servers` stays `[]`. There is no user-defined
+  custom-command creation surface (built-in slash commands only).
+
+## 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: GitHub Copilot CLI (the agent-invocable surface, distinct
+  from the IDE extension) ships a `web_fetch` tool that retrieves URL content as
+  markdown, gated by `--allow-url` / `--deny-url` permissions. This row reflects
+  the Copilot CLI tool surface; the adapter itself materializes only
+  `.github/copilot-instructions.md` and authors no tool config.
+- Evidence: vendor-doc-url
+  <https://docs.github.com/en/copilot/concepts/agents/copilot-cli/research>
+  (+ `.../how-tos/copilot-cli/set-up-copilot-cli/configure-copilot-cli`);
+  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. GitHub Copilot instruction 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
+
+GitHub Copilot documents skills (`.github/skills/<name>/SKILL.md`), hooks
+(`.github/hooks/*.json`), and CLI plugins (`plugin.json`), but **Apothem ships no
+Copilot plugin bundle** — the adapter is project-scope instructions-only, writing
+a single merged file at `<project>/.github/copilot-instructions.md` and authoring
+no other cohort. There is no Apothem-distributable standalone bundle; every
+artifact requires the full
+`apothem install --harness github-copilot --project <path>` engine run.
+
+| Artifact class | Persists standalone? | Mechanism / limit |
+|---|---|---|
+| Rules (instructions-as-text) | No — requires `apothem install` | The merged `copilot-instructions.md` (carrying the embedded behavioral mandates) is written only by the engine into the vendor-native `.github/` directory. Nothing persists before that run. |
+| Commands / Skills / Agents / Hooks | No — Apothem ships no bundle | Copilot's `plugin.json` / `.github/skills/` / `.github/hooks/` accept these cohorts, but Apothem authors no Copilot plugin; the instructions-only posture is deliberate. There is no user-defined custom-command creation surface (built-in slash commands only). |
+| MCP / Settings | No — service/IDE state | MCP lives in `~/.copilot/mcp-config.json` (IDE/service state, not a repo-writable file); the adapter authors no entries (`mcp_servers` stays `[]`). |
+
+Platform note: the vendor plugin surface exists; the Apothem-distributable
+plugin bundle does not. The merged instructions file via `apothem install` is the
+sole persistence surface.

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

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for github-copilot — project-scope install.
+
+Materializes the apothem Copilot instructions surface into the operator-
+supplied project root at ``<project>/.github/copilot-instructions.md``,
+the GA repo-wide instructions surface per
+https://docs.github.com/en/copilot/customizing-copilot/adding-custom-instructions-for-github-copilot.
+User-scope is unavailable — Copilot's user-level settings live in IDE
+state (VS Code / JetBrains UI), not a file path the harness can write.
+
+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.github_copilot.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.github_copilot.install import install as _install
+from apothem.harnesses.github_copilot.install import plan as _plan
+from apothem.harnesses.github_copilot.uninstall import uninstall as _uninstall
+from apothem.harnesses.github_copilot.update import update as _update
+from apothem.harnesses.github_copilot.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(".github") / "copilot-instructions.md"
+
+GitHubCopilotAdapter = make_project_scope_adapter(
+    "github-copilot",
+    error_label="github_copilot",
+    relative_target=_SENTINEL_RELATIVE,
+    install_fn=_install,
+    plan_fn=_plan,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="GitHubCopilotAdapter",
+)