convertible-cli 0.5.0__tar.gz → 0.7.0__tar.gz

{convertible_cli-0.5.0 → convertible_cli-0.7.0}/.markdownlint-cli2.yaml

@@ -19,6 +19,9 @@ ignores:
   - ".local/**"
   - ".afi/**"
   - ".teken/**"
+  # The virtualenv — installed packages (e.g. the [otel] extra's opentelemetry,
+  # idna) ship their own non-conformant Markdown; never lint dependencies.
+  - ".venv/**"
   # Vendored skills are cited verbatim from guildmaster — do not reformat them.
   - ".claude/skills/**"
   # devague artifacts (frames, exported specs/plans) are generated verbatim from

{convertible_cli-0.5.0 → convertible_cli-0.7.0}/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to this project will be documented in this file.
 Format follows [Keep a Changelog](https://keepachangelog.com/). This project
 adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.7.0] - 2026-05-28
+
+### Added
+
+- GPS: opt-in OpenTelemetry traces + metrics for a drive (issue #22). Spans (`convertible.drive` -> `convertible.tool.*` -> `convertible.handoff`) and metrics (steps, tokens, tool latency, tool calls, hook denials, drive duration) emit over OTLP from the loop + the shared drive path, so every engine is instrumented identically (all-engines rule).
+- `convertible telemetry status` / `overview` introspection noun, plus an explain catalog entry.
+- `TelemetryConfig` resolved from `CONVERTIBLE_OTEL_*` / standard `OTEL_*` env vars (`OTEL_SDK_DISABLED` honored as a kill-switch).
+- Optional `[otel]` extra (opentelemetry SDK + OTLP/HTTP exporter); install with `pip install "convertible-cli[otel]"`.
+
+### Changed
+
+- `loop.run()` and `execute_drive` accept/own telemetry, defaulting to a no-op resolved from the environment (mirrors the hooks pattern). Off by default it is a strict no-op: no spans, no SDK import, `TaskResult` unchanged.
+
+## [0.6.0] - 2026-05-28
+
+### Added
+
+- Layered per-model config: AGENTS instructions (`AGENTS.md` -> `AGENTS.convertible.md` -> `AGENTS.convertible.<model>.md` at the repo root, with a `~/.convertible/` fallback) and skills (`.convertible/skills/*.md` -> `.convertible/<model>/skills/*.md`) compose into the engine system prompt via `convertible/layers.py`
+- `convertible agents` and `convertible skills` introspection nouns (list + overview, `--json`, `--model`)
+- `Engine.system_prompt()` base-class helper injects the layered prompt for every engine (all-engines rule)
+
+### Changed
+
+- Both engines (mock, vllm-openai) now pass a model-specific `system_prompt` to the loop; behavior is byte-identical when no AGENTS/skills files exist
+
 ## [0.5.0] - 2026-05-27
 
 ### Changed

{convertible_cli-0.5.0 → convertible_cli-0.7.0}/CLAUDE.md

@@ -21,6 +21,11 @@ The car metaphor *is* the architecture:
 - **Wheels** — engines are plugins discovered via the `convertible.engines`
   Python entry-point group (`convertible/registry.py`).
 - **Dashboard** — the JSON result artifact + step trace (`convertible/artifact.py`).
+- **GPS** — opt-in OpenTelemetry traces + metrics (`convertible/telemetry/`).
+  Instrumented in the loop + the shared drive path so every engine emits it
+  (all-engines rule), exactly like hooks. Off by default; the OpenTelemetry SDK
+  is an optional `[otel]` extra, imported lazily, so the base install stays
+  dep-free. Surfaced via the `telemetry` introspection noun.
 - **Handoff** — branch/commit/push + `gh pr create`, gated for offline/CI
   (`convertible/handoff.py`).
 - **Command templates** — named, parameterized task recipes in
@@ -34,6 +39,16 @@ The car metaphor *is* the architecture:
   code path, no daemon.
 - **Config resolution** — `convertible/configdir.py`: repo-level
   `.convertible/` overrides user-level `~/.convertible/`.
+- **Layered per-model config** — `convertible/layers.py`: AGENTS instructions
+  (`AGENTS.md` → `AGENTS.convertible.md` → `AGENTS.convertible.<model>.md`, at
+  the repo root with a `~/.convertible/` fallback) and skills
+  (`.convertible/skills/*.md` → `.convertible/<model>/skills/*.md`) compose into
+  the engine system prompt. Resolution builds exact paths for the current model
+  and never globs sibling models — per-model isolation is structural. Injected
+  once on the `Engine` base class (`system_prompt()`), so every engine inherits
+  it (all-engines rule). Surfaced via the `agents` / `skills` introspection
+  nouns. **MCP layering is not built** — convertible reads no `mcp.json` and has
+  no `mcp` verb; a live MCP client is a re-spec (see scope below).
 
 The buildable spec and plan this implementation converged from live in
 [`docs/specs/`](docs/specs/) and [`docs/plans/`](docs/plans/) (authored via the
@@ -43,14 +58,21 @@ The buildable spec and plan this implementation converged from live in
 
 In scope: the chassis, the entry-point wheel contract, exactly two engines
 (`mock`, `vllm-openai`), the git/PR handoff, command templates, lifecycle
-hooks, and the foreground interactive palette.
+hooks, the foreground interactive palette, layered per-model AGENTS/skills
+config (`convertible/layers.py`), and GPS — opt-in OpenTelemetry traces +
+metrics (`convertible/telemetry/`), with the SDK as an optional `[otel]` extra.
 
 **Out of scope for v0** — do not add without re-speccing: a multi-engine
 router/policy "gearbox", an execution sandbox, a daemon/server mode,
-Codex/Claude/Gemini drivers, and a per-repo hook trust gate / `--no-hooks`
+Codex/Claude/Gemini drivers, a per-repo hook trust gate / `--no-hooks`
 escape hatch (planned follow-up hardening — not yet built; document this gap
-honestly, never invent a `--no-hooks` flag). Adding an excluded feature means
-scope crept.
+honestly, never invent a `--no-hooks` flag), and an **MCP execution runtime**
+(a live MCP client — stdio/socket transport, tool discovery, dynamic tool
+registration). The layered config ships AGENTS + skills only; `mcp.json` is
+**not** read and there is no `mcp` verb. A live MCP client would breach the
+no-deps / no-socket / no-daemon conventions and needs its own spec — document
+this gap honestly, never invent an `mcp` surface. Adding an excluded feature
+means scope crept.
 
 ## The all-engines rule
 
@@ -65,7 +87,15 @@ test (`tests/test_e2e_mock.py`) is the guard.
 - **No runtime dependencies.** `pyproject.toml` keeps `dependencies = []`; the
   vLLM driver speaks the OpenAI wire format over stdlib `urllib`; commands and
   hooks use only stdlib (`json`, `subprocess`, `pathlib`). Don't add a runtime
-  dep without a strong reason — dev-only deps go in the `dev` group.
+  dep without a strong reason — dev-only deps go in the `dev` group. The one
+  documented exception is **GPS**: the OpenTelemetry SDK ships as an optional
+  `[project.optional-dependencies] otel` extra, never a base dependency. It is
+  imported **lazily** inside `convertible/telemetry/_otel.py` (only when
+  telemetry is enabled), so `dependencies = []` and the zero-deps guard
+  (`tests/test_zero_deps.py`) still hold — the guard imports `convertible.loop`
+  / `convertible.telemetry` / `convertible.cli` and asserts no third-party leak
+  even with the extra installed. Keep the SDK confined to `_otel.py`; never
+  import `opentelemetry` from any other convertible module.
 - **Agent-first CLI.** New verbs are `convertible/cli/_commands/` modules with a
   `register(sub)`, wired in `convertible/cli/__init__.py`. Results to stdout,
   diagnostics/errors to stderr (never mixed); every command supports `--json`;
@@ -82,6 +112,11 @@ test (`tests/test_e2e_mock.py`) is the guard.
   hook firing — new engine wheels inherit the full lifecycle layer automatically
   and must not duplicate it. The all-engines rule applies: a hook config that
   fires on `mock` must fire identically on `vllm-openai`.
+- **Telemetry belongs to the chassis too.** `convertible/loop.py` (per tool
+  call) and the shared `execute_drive` path (root + handoff spans) own all
+  telemetry; no engine module touches the `telemetry` package. Off by default it
+  is a strict no-op (no spans, no SDK import, `TaskResult` unchanged) — protect
+  that so the e2e shape test and zero-deps guard keep passing.
 - **Repo-shipped hooks run by default (trusted-operator-env model D2).** There
   is no `--no-hooks` flag today. A per-repo trust gate is a tracked follow-up.
   Document this gap clearly; never document a non-existent flag.
@@ -102,6 +137,13 @@ uv run convertible hooks list --repo .             # list configured hooks
 uv run convertible hooks overview                  # surface description
 uv run convertible session --repo . --engine mock  # interactive palette
 
+# GPS / telemetry (opt-in; needs the [otel] extra):
+uv run convertible telemetry status                # resolved telemetry config
+uv run convertible telemetry overview              # surface description
+uv sync --extra otel                               # install the OpenTelemetry SDK
+CONVERTIBLE_OTEL_ENABLED=1 OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318 \
+  uv run convertible drive "<task>" --repo . --engine mock --no-pr  # emits a trace
+
 # Lint + gates CI enforces:
 uv run black --check convertible tests
 uv run isort --check-only convertible tests

convertible_cli-0.5.0/README.md → convertible_cli-0.7.0/PKG-INFO

@@ -1,3 +1,25 @@
+Metadata-Version: 2.4
+Name: convertible-cli
+Version: 0.7.0
+Summary: Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract.
+Project-URL: Homepage, https://github.com/agentculture/convertible
+Project-URL: Issues, https://github.com/agentculture/convertible/issues
+Author: AgentCulture
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Provides-Extra: otel
+Requires-Dist: opentelemetry-api>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-exporter-otlp-proto-http>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-sdk>=1.25; extra == 'otel'
+Requires-Dist: opentelemetry-semantic-conventions>=0.46b0; extra == 'otel'
+Description-Content-Type: text/markdown
+
 # convertible
 
 ```text
@@ -42,6 +64,7 @@ which one ran.
 | **Tool-loop** | the bounded agentic loop the engine drives the repo through |
 | **Wheels** | replaceable engine plugins, discovered via Python entry points |
 | **Dashboard** | the JSON result artifact + step trace each run writes |
+| **GPS** | opt-in OpenTelemetry traces + metrics (`convertible/telemetry/`) |
 | **Garage** | `convertible wheels list` — the engines installed in this env |
 
 ## What ships in v0
@@ -313,6 +336,82 @@ The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
 
+## GPS: OpenTelemetry observability
+
+A drive can emit **OpenTelemetry traces + metrics** so it's observable against an
+OTLP collector — not just the per-run JSON artifact. Telemetry lives in the
+chassis (the loop + the shared drive path), so **every engine** emits it
+identically, exactly like lifecycle hooks.
+
+It is **off by default** and a strict no-op when off (no spans, no SDK import,
+the result artifact unchanged). The OpenTelemetry SDK is an **optional extra** —
+the base install keeps zero runtime dependencies:
+
+```bash
+pip install 'convertible-cli[otel]'                 # or: uv sync --extra otel
+export CONVERTIBLE_OTEL_ENABLED=1
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # OTLP/HTTP collector
+uv run convertible drive "<task>" --repo . --engine mock --no-pr
+#   -> stderr prints "trace: <id>"; the collector receives the spans + metrics
+```
+
+Requested without the extra installed, convertible degrades to a no-op with a
+one-line stderr notice — it never fails the drive.
+
+**Signals.** Spans: `convertible.drive` (root) → `convertible.tool.*` (per tool
+call) → `convertible.handoff`. Metrics: `convertible.steps`, `convertible.tokens`,
+`convertible.tool.latency`, `convertible.tool.calls`, `convertible.hook.denials`,
+`convertible.drive.duration`.
+
+**Config** (precedence: explicit > `CONVERTIBLE_OTEL_*` > standard `OTEL_*` >
+default): `CONVERTIBLE_OTEL_ENABLED`, `CONVERTIBLE_OTEL_ENDPOINT` /
+`OTEL_EXPORTER_OTLP_ENDPOINT`, `CONVERTIBLE_OTEL_SERVICE_NAME` /
+`OTEL_SERVICE_NAME`. `OTEL_SDK_DISABLED=true` is honored as a kill-switch.
+
+```bash
+uv run convertible telemetry status      # resolved config + whether the SDK is installed
+uv run convertible telemetry overview    # describe the surface
+```
+
+## Per-model instructions & skills
+
+Convertible composes a model-specific **system prompt** for every drive from two
+layered families, resolved *relative to the model currently driving*. Strict
+per-model isolation: driving model X reads only X's overlay plus the shared base
+— it never even opens model Y's files (isolation is structural, built from exact
+paths, not filtered).
+
+**AGENTS instructions** cascade from the **repo root** (the cross-tool standard
+location — sibling agent tools read `AGENTS.md` there too), general → specific,
+with a `~/.convertible/` user-level fallback:
+
+```text
+AGENTS.md                       # shared base
+AGENTS.convertible.md           # convertible overlay
+AGENTS.convertible.<model>.md   # model overlay
+```
+
+**Skills** are markdown capability docs under `.convertible/`, folded into the
+prompt as a compact name + one-line-summary catalog (a skill is instructional
+text only — there is no skill *execution* in v0):
+
+```text
+.convertible/skills/*.md            # base
+.convertible/<model>/skills/*.md    # model overlay (shadows base by stem)
+```
+
+`<model>` is sanitized to a filename-safe token (e.g. `Qwen/Qwen3-32B` →
+`Qwen-Qwen3-32B`). Inspect what resolves for a model:
+
+```bash
+uv run convertible agents list --model Qwen/Qwen3-32B --repo .
+uv run convertible skills list --model Qwen/Qwen3-32B --repo .
+```
+
+> **MCP layering is not built yet.** Convertible does not read `mcp.json` or
+> connect to any MCP server today; a live MCP client needs its own spec. There
+> is no `mcp` verb — don't rely on a non-existent surface.
+
 ## ⚠ Security: repo-shipped hooks run by default
 
 > **This is a code-execution risk. Read before driving an untrusted repo.**
@@ -351,6 +450,12 @@ rely on a non-existent flag.
 | `commands overview` | Describe the commands surface. |
 | `hooks list` | List configured hook entries for a repo. |
 | `hooks overview` | Describe the hooks surface. |
+| `agents list` | List resolved AGENTS instruction layers for a model. |
+| `agents overview` | Describe the agents surface. |
+| `skills list` | List resolved skill docs for a model. |
+| `skills overview` | Describe the skills surface. |
+| `telemetry status` | Show the resolved GPS / OpenTelemetry config + whether the SDK is installed. |
+| `telemetry overview` | Describe the telemetry surface. |
 | `session` | Open a foreground interactive palette. |
 | `wheels list` | List discovered engine wheels (the garage). |
 | `whoami` | Report this agent's nick, version, backend, and model. |

convertible_cli-0.5.0/PKG-INFO → convertible_cli-0.7.0/README.md

@@ -1,20 +1,3 @@
-Metadata-Version: 2.4
-Name: convertible-cli
-Version: 0.5.0
-Summary: Convertible CLI is a swappable coder-agent harness that turns different models into repo workers behind one shared task contract.
-Project-URL: Homepage, https://github.com/agentculture/convertible
-Project-URL: Issues, https://github.com/agentculture/convertible/issues
-Author: AgentCulture
-License-Expression: MIT
-License-File: LICENSE
-Classifier: Development Status :: 3 - Alpha
-Classifier: Intended Audience :: Developers
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Topic :: Software Development
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-
 # convertible
 
 ```text
@@ -59,6 +42,7 @@ which one ran.
 | **Tool-loop** | the bounded agentic loop the engine drives the repo through |
 | **Wheels** | replaceable engine plugins, discovered via Python entry points |
 | **Dashboard** | the JSON result artifact + step trace each run writes |
+| **GPS** | opt-in OpenTelemetry traces + metrics (`convertible/telemetry/`) |
 | **Garage** | `convertible wheels list` — the engines installed in this env |
 
 ## What ships in v0
@@ -330,6 +314,82 @@ The session loops until the user enters `q`, `quit`, or an empty line. Any
 driver flags accepted by `drive` (`--engine`, `--no-pr`, `--base-url`, etc.)
 are also accepted by `session`.
 
+## GPS: OpenTelemetry observability
+
+A drive can emit **OpenTelemetry traces + metrics** so it's observable against an
+OTLP collector — not just the per-run JSON artifact. Telemetry lives in the
+chassis (the loop + the shared drive path), so **every engine** emits it
+identically, exactly like lifecycle hooks.
+
+It is **off by default** and a strict no-op when off (no spans, no SDK import,
+the result artifact unchanged). The OpenTelemetry SDK is an **optional extra** —
+the base install keeps zero runtime dependencies:
+
+```bash
+pip install 'convertible-cli[otel]'                 # or: uv sync --extra otel
+export CONVERTIBLE_OTEL_ENABLED=1
+export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318   # OTLP/HTTP collector
+uv run convertible drive "<task>" --repo . --engine mock --no-pr
+#   -> stderr prints "trace: <id>"; the collector receives the spans + metrics
+```
+
+Requested without the extra installed, convertible degrades to a no-op with a
+one-line stderr notice — it never fails the drive.
+
+**Signals.** Spans: `convertible.drive` (root) → `convertible.tool.*` (per tool
+call) → `convertible.handoff`. Metrics: `convertible.steps`, `convertible.tokens`,
+`convertible.tool.latency`, `convertible.tool.calls`, `convertible.hook.denials`,
+`convertible.drive.duration`.
+
+**Config** (precedence: explicit > `CONVERTIBLE_OTEL_*` > standard `OTEL_*` >
+default): `CONVERTIBLE_OTEL_ENABLED`, `CONVERTIBLE_OTEL_ENDPOINT` /
+`OTEL_EXPORTER_OTLP_ENDPOINT`, `CONVERTIBLE_OTEL_SERVICE_NAME` /
+`OTEL_SERVICE_NAME`. `OTEL_SDK_DISABLED=true` is honored as a kill-switch.
+
+```bash
+uv run convertible telemetry status      # resolved config + whether the SDK is installed
+uv run convertible telemetry overview    # describe the surface
+```
+
+## Per-model instructions & skills
+
+Convertible composes a model-specific **system prompt** for every drive from two
+layered families, resolved *relative to the model currently driving*. Strict
+per-model isolation: driving model X reads only X's overlay plus the shared base
+— it never even opens model Y's files (isolation is structural, built from exact
+paths, not filtered).
+
+**AGENTS instructions** cascade from the **repo root** (the cross-tool standard
+location — sibling agent tools read `AGENTS.md` there too), general → specific,
+with a `~/.convertible/` user-level fallback:
+
+```text
+AGENTS.md                       # shared base
+AGENTS.convertible.md           # convertible overlay
+AGENTS.convertible.<model>.md   # model overlay
+```
+
+**Skills** are markdown capability docs under `.convertible/`, folded into the
+prompt as a compact name + one-line-summary catalog (a skill is instructional
+text only — there is no skill *execution* in v0):
+
+```text
+.convertible/skills/*.md            # base
+.convertible/<model>/skills/*.md    # model overlay (shadows base by stem)
+```
+
+`<model>` is sanitized to a filename-safe token (e.g. `Qwen/Qwen3-32B` →
+`Qwen-Qwen3-32B`). Inspect what resolves for a model:
+
+```bash
+uv run convertible agents list --model Qwen/Qwen3-32B --repo .
+uv run convertible skills list --model Qwen/Qwen3-32B --repo .
+```
+
+> **MCP layering is not built yet.** Convertible does not read `mcp.json` or
+> connect to any MCP server today; a live MCP client needs its own spec. There
+> is no `mcp` verb — don't rely on a non-existent surface.
+
 ## ⚠ Security: repo-shipped hooks run by default
 
 > **This is a code-execution risk. Read before driving an untrusted repo.**
@@ -368,6 +428,12 @@ rely on a non-existent flag.
 | `commands overview` | Describe the commands surface. |
 | `hooks list` | List configured hook entries for a repo. |
 | `hooks overview` | Describe the hooks surface. |
+| `agents list` | List resolved AGENTS instruction layers for a model. |
+| `agents overview` | Describe the agents surface. |
+| `skills list` | List resolved skill docs for a model. |
+| `skills overview` | Describe the skills surface. |
+| `telemetry status` | Show the resolved GPS / OpenTelemetry config + whether the SDK is installed. |
+| `telemetry overview` | Describe the telemetry surface. |
 | `session` | Open a foreground interactive palette. |
 | `wheels list` | List discovered engine wheels (the garage). |
 | `whoami` | Report this agent's nick, version, backend, and model. |

{convertible_cli-0.5.0 → convertible_cli-0.7.0}/convertible/cli/__init__.py

@@ -73,6 +73,7 @@ def _stdio_is_interactive() -> bool:
 
 
 def _build_parser() -> argparse.ArgumentParser:
+    from convertible.cli._commands import agents as _agents_group
     from convertible.cli._commands import cli as _cli_group
     from convertible.cli._commands import commands as _commands_group
     from convertible.cli._commands import doctor as _doctor_cmd
@@ -82,6 +83,8 @@ def _build_parser() -> argparse.ArgumentParser:
     from convertible.cli._commands import learn as _learn_cmd
     from convertible.cli._commands import overview as _overview_cmd
     from convertible.cli._commands import session as _session_cmd
+    from convertible.cli._commands import skills as _skills_group
+    from convertible.cli._commands import telemetry as _telemetry_group
     from convertible.cli._commands import wheels as _wheels_group
     from convertible.cli._commands import whoami as _whoami_cmd
 
@@ -110,6 +113,11 @@ def _build_parser() -> argparse.ArgumentParser:
     # Extensibility layer: command templates + lifecycle hooks.
     _commands_group.register(sub)
     _hooks_group.register(sub)
+    # Layered per-model config: AGENTS instructions + skills.
+    _agents_group.register(sub)
+    _skills_group.register(sub)
+    # GPS: OpenTelemetry traces + metrics (opt-in, optional [otel] extra).
+    _telemetry_group.register(sub)
     # Interactive foreground palette (c28/R8).
     _session_cmd.register(sub)
 

convertible_cli-0.7.0/convertible/cli/_commands/agents.py

@@ -0,0 +1,109 @@
+"""``convertible agents`` — inspect layered AGENTS instruction files.
+
+``agents list`` resolves the AGENTS instruction cascade for a model
+(``AGENTS.md`` -> ``AGENTS.convertible.md`` -> ``AGENTS.convertible.<model>.md``;
+repo root with a ``~/.convertible/`` fallback) and reports the layers that
+exist, in general -> specific order. ``agents overview`` describes the noun
+(satisfying the agent-first rubric: any noun with action-verbs must also expose
+``overview``).
+
+These layers are composed (with the engine default and the skills catalog) into
+the system prompt every drive sends — so what ``agents list`` reports for a model
+is exactly what that model is instructed with. Per-model isolation is structural:
+only the named model's overlay is read, never a sibling model's.
+"""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from convertible.cli._commands.overview import emit_overview
+from convertible.cli._output import emit_result
+from convertible.config import EngineConfig
+from convertible.layers import resolve_agents
+
+
+def _agents_sections() -> list[dict[str, object]]:
+    return [
+        {
+            "title": "What it does",
+            "items": [
+                "Resolves AGENTS instruction layers for the current model",
+                "Cascade (general -> specific): AGENTS.md, AGENTS.convertible.md, "
+                "AGENTS.convertible.<model>.md",
+                "Read from the repo root, with a ~/.convertible/ user-level fallback",
+                "Composed into the system prompt every drive sends to the engine",
+            ],
+        },
+        {
+            "title": "Per-model isolation",
+            "items": [
+                "<model> is sanitized (e.g. 'Qwen/Qwen3-32B' -> 'Qwen-Qwen3-32B')",
+                "Only the named model's overlay is read — never a sibling model's",
+                "MCP layering is not built yet (no mcp.json reader); tracked separately",
+            ],
+        },
+        {
+            "title": "Verbs",
+            "items": [
+                "agents list [--model M] [--repo PATH] — list resolved AGENTS layers",
+                "agents overview — describe the agents surface (this command)",
+            ],
+        },
+    ]
+
+
+def cmd_agents_overview(args: argparse.Namespace) -> int:
+    emit_overview(
+        "convertible agents",
+        _agents_sections(),
+        json_mode=bool(getattr(args, "json", False)),
+    )
+    return 0
+
+
+def cmd_agents_list(args: argparse.Namespace) -> int:
+    repo = Path(getattr(args, "repo", ".")).expanduser()
+    model = getattr(args, "model", None) or EngineConfig.resolve().model
+    json_mode = bool(getattr(args, "json", False))
+
+    layers = resolve_agents(repo, model)
+
+    if json_mode:
+        items = [{"scope": layer.scope, "path": str(layer.path)} for layer in layers]
+        emit_result({"model": model, "agents": items}, json_mode=True)
+    elif not layers:
+        emit_result("(no AGENTS layers found)", json_mode=False)
+    else:
+        lines = [f"{layer.scope}\t{layer.path}" for layer in layers]
+        emit_result("\n".join(lines), json_mode=False)
+    return 0
+
+
+def _no_verb(args: argparse.Namespace) -> int:
+    return cmd_agents_overview(args)
+
+
+def register(sub: argparse._SubParsersAction) -> None:
+    p = sub.add_parser(
+        "agents",
+        help="Inspect layered AGENTS instruction files (see 'convertible agents overview').",
+    )
+    p.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    p.set_defaults(func=_no_verb, json=False)
+    noun_sub = p.add_subparsers(dest="agents_command", parser_class=type(p))
+
+    lst = noun_sub.add_parser("list", help="List resolved AGENTS instruction layers.")
+    lst.add_argument("--repo", default=".", help="Path to the target repository (default: cwd).")
+    lst.add_argument(
+        "--model",
+        default=None,
+        help="Model to resolve layers for (default: the resolved engine model).",
+    )
+    lst.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    lst.set_defaults(func=cmd_agents_list)
+
+    ov = noun_sub.add_parser("overview", help="Describe the agents surface.")
+    ov.add_argument("--json", action="store_true", help="Emit structured JSON.")
+    ov.set_defaults(func=cmd_agents_overview)

{convertible_cli-0.5.0 → convertible_cli-0.7.0}/convertible/cli/_commands/drive.py

@@ -33,6 +33,7 @@ from convertible.commands import CommandError, expand_command
 from convertible.config import EngineConfig
 from convertible.contract import OK, Task, TaskResult
 from convertible.handoff import HandoffError, handoff
+from convertible.telemetry import load_telemetry
 
 
 def _render(result: TaskResult, engine: str, artifact_path: Path) -> str:
@@ -103,39 +104,69 @@ def execute_drive(
             EXIT_USER_ERROR, str(exc), "list engines with: convertible wheels list"
         ) from exc
 
+    # GPS: the root span wraps engine.drive() + handoff() + the artifact write, so
+    # the loop's tool spans nest under it. A no-op unless telemetry is enabled.
+    # The same shared path serves `drive` and `session`, so both are instrumented.
+    telemetry = load_telemetry()
     try:
-        result = engine.drive(task, config)
-    except Exception as exc:  # noqa: BLE001 - any failure still writes an artifact (h5)
-        result = failed_result(task.id, f"{type(exc).__name__}: {exc}")
-        result.command = command_name
-        write(result, artifact_dir(repo))
-        raise CliError(
-            EXIT_ENV_ERROR,
-            f"engine '{engine_name}' failed: {exc}",
-            "check the engine config / vLLM server; a result artifact was still written",
-        ) from exc
+        with telemetry.drive_span(
+            task_id=task.id,
+            engine=engine_name,
+            model=config.model,
+            max_steps=config.max_steps,
+        ) as drive_span:
+            trace_id = telemetry.trace_id_hex()
+            if trace_id:
+                emit_diagnostic(f"trace: {trace_id}")
 
-    if result.status == OK:
-        try:
-            outcome = handoff(
-                repo,
-                task.id,
-                instruction=task.instruction,
-                open_pr=open_pr,
-                base_branch=base,
+            try:
+                result = engine.drive(task, config)
+            except Exception as exc:  # noqa: BLE001 - any failure still writes an artifact (h5)
+                result = failed_result(task.id, f"{type(exc).__name__}: {exc}")
+                result.command = command_name
+                drive_span.set(status=result.status)
+                write(result, artifact_dir(repo))
+                raise CliError(
+                    EXIT_ENV_ERROR,
+                    f"engine '{engine_name}' failed: {exc}",
+                    "check the engine config / vLLM server; a result artifact was still written",
+                ) from exc
+
+            if result.status == OK:
+                with telemetry.handoff_span() as handoff_span:
+                    try:
+                        outcome = handoff(
+                            repo,
+                            task.id,
+                            instruction=task.instruction,
+                            open_pr=open_pr,
+                            base_branch=base,
+                        )
+                        result.branch = outcome.branch
+                        result.pr_url = outcome.pr_url
+                        if not result.changed_files:
+                            result.changed_files = outcome.changed_files
+                        handoff_span.set(
+                            branch=outcome.branch,
+                            committed=outcome.committed,
+                            pushed=outcome.pushed,
+                            pr_url=outcome.pr_url,
+                        )
+                        if outcome.note:
+                            emit_diagnostic(f"handoff: {outcome.note}")
+                    except HandoffError as exc:
+                        emit_diagnostic(f"handoff skipped: {exc}")
+
+            drive_span.set(
+                status=result.status,
+                step_count=len(result.steps),
+                pr_url=result.pr_url,
             )
-            result.branch = outcome.branch
-            result.pr_url = outcome.pr_url
-            if not result.changed_files:
-                result.changed_files = outcome.changed_files
-            if outcome.note:
-                emit_diagnostic(f"handoff: {outcome.note}")
-        except HandoffError as exc:
-            emit_diagnostic(f"handoff skipped: {exc}")
-
-    result.command = command_name
-    artifact_path = write(result, artifact_dir(repo))
-    return result, artifact_path
+            result.command = command_name
+            artifact_path = write(result, artifact_dir(repo))
+            return result, artifact_path
+    finally:
+        telemetry.flush()
 
 
 def cmd_drive(args: argparse.Namespace) -> int:

{convertible_cli-0.5.0 → convertible_cli-0.7.0}/convertible/cli/_commands/overview.py

@@ -27,6 +27,8 @@ _ARTIFACTS = [
 _VERBS = [
     "drive <instruction> — run a repo task through a coder engine",
     "wheels list — list discovered engine wheels",
+    "agents list — inspect layered AGENTS instruction files for a model",
+    "skills list — inspect layered skill docs for a model",
     "whoami — identity probe (nick, version, backend, model)",
     "learn — structured self-teaching prompt",
     "explain <path> — markdown docs for a topic",