@ahmed-g-gad/apothem 0.1.1

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

@@ -0,0 +1,87 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Qwen Code Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification against `qwenlm.github.io/qwen-code-docs` + `github.com/QwenLM/qwen-code` — `~/.qwen/QWEN.md` (`context.fileName`, `@path` imports, `/memory` reload), Markdown+YAML custom commands (TOML deprecated), and settings.json / `mcpServers` / `.qwen/skills/` / hooks all confirmed current.
+- Adapter source: `src/apothem/harnesses/qwen_code/`
+- Evidence level: vendor-doc pinned (live re-fetch 2026-05-31) at release tag
+  `v0.17.0` for `~/.qwen/settings.json`, `QWEN.md` (`context.fileName`),
+  Markdown+YAML commands (TOML deprecated), `.qwen/skills/`, SubAgents
+  (Markdown+YAML), `mcpServers`, settings hooks, and `.qwenignore`. The
+  `settings.json` config renders directly (no Jinja template); the shipped
+  instruction template is `templates/QWEN.md`. No vendor-native UI claim is made
+  here. Docs pages are mutable — no-immutable-source exception anchored to the
+  immutable release tag `v0.17.0`.
+- Official references:
+  - <https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/>
+  - <https://qwenlm.github.io/qwen-code-docs/en/users/features/commands/>
+  - <https://qwenlm.github.io/qwen-code-docs/en/users/features/sub-agents/>
+  - <https://qwenlm.github.io/qwen-code-docs/en/users/features/skills/>
+  - <https://qwenlm.github.io/qwen-code-docs/en/users/features/hooks/>
+  - <https://qwenlm.github.io/qwen-code-docs/en/users/configuration/qwen-ignore/>
+
+## 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: qwen-code ships a built-in `web_fetch` tool (URL
+  retrieval), but the built-in `web_search` tool was removed and web search is
+  now MCP-only (a documented breaking change). The `partial` subset boundary is:
+  fetch yes, search via MCP only.
+- Evidence: vendor-doc-url
+  <https://github.com/QwenLM/qwen-code/blob/8f8ed0d7c184208ac3fc4b92020b207cec453723/docs/developers/tools/introduction.md>
+  (web_fetch listed built-in) +
+  <https://github.com/QwenLM/qwen-code/blob/8f8ed0d7c184208ac3fc4b92020b207cec453723/docs/developers/tools/web-search.md>
+  (web_search removed, MCP-only); commit-sha
+  `8f8ed0d7c184208ac3fc4b92020b207cec453723` (default-branch HEAD, both blobs
+  confirmed reachable at this commit); snapshot-date 2026-06-21.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Qwen Code adapter output preserves that suffix when prompt text is materialized.
+- 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
+
+Qwen Code exposes a vendor extension surface (`qwen extensions install`). The
+repo root IS the extension root: `qwen-extension.json` (manifest), `QWEN.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-target cohort still requires the engine, which converts each Apothem
+artifact to its Qwen-native shape (Markdown+YAML commands/agents, `.qwen/skills/`).
+
+| Artifact class | Persists extension-alone? | Mechanism / limit |
+|---|---|---|
+| Context anchor (rules-as-text) | Yes | `QWEN.md` is loaded as session context by `context.fileName`; 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 (`~/.qwen/commands/`) requires `apothem install`. |
+| Skills | No — requires `apothem install` | The extension manifest bundles no skills; `~/.qwen/skills/*/SKILL.md` lands only via the engine. |
+| Rules (as native primitive) | No — platform limit | Qwen Code has no native rules-directory primitive; Apothem rules persist as the `QWEN.md` context text above, or as the engine-installed `~/.qwen/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 `~/.qwen/apothem/hooks/`. |
+| MCP servers | No — operator-owned | `mcpServers` lives in operator-owned `~/.qwen/settings.json`; neither the extension manifest nor the engine authors MCP entries. |
+| Tools / settings | No — operator-owned | `~/.qwen/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
+sub-agent cohort into the extension package is a documented future enhancement —
+the conversion logic lives in the engine (`markdown_commands` / `qwen_agents`
+modes in `propagation-manifest.yaml`), so a build step that pre-renders those
+into a bundled `commands/` + `.qwen/` tree would let the extension carry the
+cohort without a post-install engine run.

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

@@ -0,0 +1,37 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for qwen-code.
+
+Materializes ``~/.qwen/settings.json`` from the shared profile per the
+qwen-code vendor canonical schema at
+https://qwenlm.github.io/qwen-code-docs/en/users/configuration/settings/;
+the adapter-local
+``STANDARD-CONVENTION-PIN.md`` records the current convention snapshot.
+The install step also writes ``QWEN.md``, registers native hooks, and
+propagates Apothem commands, skills, and agents into Qwen Code's native
+Markdown discovery directories.
+Delegates installation to :mod:`apothem.harnesses.qwen_code.materializer`.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared.wrapper_factories import make_native_config_adapter
+from apothem.harnesses.qwen_code.install import install as _install
+from apothem.harnesses.qwen_code.materializer import (
+    materialize_native_config as materialize_native_config,
+)
+from apothem.harnesses.qwen_code.uninstall import uninstall as _uninstall
+from apothem.harnesses.qwen_code.update import update as _update
+from apothem.harnesses.qwen_code.verify import verify as _verify
+
+QwenCodeAdapter = make_native_config_adapter(
+    "qwen-code",
+    target_factory=lambda: Path.home() / ".qwen/settings.json",
+    install_fn=_install,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="QwenCodeAdapter",
+)

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

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. qwen_code
+# anchors ~/.qwen/settings.json and QWEN.md, then uses Qwen Code's documented
+# commands, skills (.qwen/skills/), and SubAgents discovery directories.
+# Commands are Markdown + YAML (TOML is deprecated). MCP is declared within
+# settings.json's mcpServers namespace. settings.json renders directly (no Jinja
+# template); the shipped instruction template is templates/QWEN.md.
+
+mcp_servers:
+  - settings.json-mcpServers-namespace
+# The adapter's materializer.py authors this MCP block from the shared profile.
+mcp_servers_authored: true
+sub_agent_dispatch: true
+custom_command_support: "markdown"
+recommended_postfix_rendering: "plain-text"
+long_context_compaction: "profile-managed"
+context_ignore_surface: "qwenignore-and-settings-mediated"
+layered_context_surface: "settings.json hooks plus QWEN.md hierarchical context"
+lsp_symbol_navigation: "tracked-gap-no-adapter-owned-LSP-surface"
+hook_learning_capture: "settings.json-hooks"
+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: qwen-code ships a built-in
+# `web_fetch` tool (URL retrieval), but the built-in `web_search` tool was
+# removed and web search is now MCP-only (a documented breaking change). The
+# `partial` subset boundary is: fetch yes, search via MCP only. Evidence triple
+# — vendor-doc-url:
+# https://github.com/QwenLM/qwen-code/blob/main/docs/developers/tools/introduction.md
+# (web_fetch listed built-in) + .../docs/developers/tools/web-search.md
+# (web_search removed); commit-sha: main-branch (no commit-pinned blob reachable
+# at fetch time — main is the most authoritative reachable form); 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 and the subset boundary to the pin.
+web_fetch: "partial"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "templates/QWEN.md"
+agent_memory_surface: "n/a"

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

@@ -0,0 +1,19 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the qwen-code harness adapter."""
+
+from __future__ import annotations
+
+from apothem.harnesses._shared.wrapper_factories import make_native_config_install
+from apothem.harnesses.qwen_code.materializer import materialize_native_config
+
+_HARNESS_NAME: str = "qwen_code"
+_HARNESS_ID: str = "qwen-code"
+
+install = make_native_config_install(
+    _HARNESS_NAME,
+    materialize_native_config,
+    harness_id=_HARNESS_ID,
+    render_tokens=True,
+    support_profile=True,
+)

package/src/apothem/harnesses/qwen_code/materializer.py

@@ -0,0 +1,174 @@
+# SPDX-License-Identifier: MIT
+
+"""Materializer for the qwen-code harness — renders JSON settings config.
+
+Qwen Code's canonical user configuration surface is ``~/.qwen/settings.json``.
+Apothem also installs ``~/.qwen/QWEN.md`` as the user-scope context anchor and
+places commands, skills, and subagents in Qwen Code's native discovery
+directories. Non-native support cohorts stay under ``~/.qwen/apothem/``. This
+materializer renders only documented settings keys and lifecycle hook entries.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from apothem.lib.profile import coerce_profile
+from apothem.lib.profile_projection import mcp_servers_for, render_mcp_standard
+
+# Per-event hook-timeout budgets (milliseconds), keyed to the hook-event classes
+# in rules/performance-discipline.md §1: PreToolUse = 10s, SessionStart /
+# PreCompact / PostCompact = 30s, Stop = 60s. Named here so the budgets are
+# documented intent rather than repeated magic numbers (M13.10).
+_PRETOOLUSE_TIMEOUT_MS = 10_000
+_SESSION_TIMEOUT_MS = 30_000
+_STOP_TIMEOUT_MS = 60_000
+
+
+def _hook(command: str, timeout: int, description: str) -> dict[str, object]:
+    return {
+        "type": "command",
+        "command": command,
+        "timeout": timeout,
+        "description": description,
+    }
+
+
+def _dispatch(event_name: str, message_name: str | None = None) -> str:
+    """Render a hook command that invokes the installed dispatcher by path.
+
+    The ``${HARNESS_ROOT}`` token resolves at install time (the adapter's
+    install step renders content tokens before writing), so the command
+    points at the dispatcher materialized under ``~/.qwen/apothem/hooks/``
+    without requiring an importable ``apothem`` package on the host.
+    """
+    parts = ["python", '"${HARNESS_ROOT}/apothem/hooks/dispatch.py"', event_name]
+    if message_name:
+        parts.append(message_name)
+    return " ".join(parts)
+
+
+def _qwen_hooks() -> dict[str, list[dict[str, object]]]:
+    return {
+        "SessionStart": [
+            {
+                "hooks": [
+                    _hook(
+                        _dispatch("SessionStart"),
+                        _SESSION_TIMEOUT_MS,
+                        "Initialize Apothem session posture.",
+                    ),
+                ],
+            },
+        ],
+        "PreToolUse": [
+            {
+                "matcher": "^Bash$",
+                "hooks": [
+                    _hook(
+                        _dispatch("PreToolUse", "pretooluse-bash"),
+                        _PRETOOLUSE_TIMEOUT_MS,
+                        "Validate shell command safety and isolation.",
+                    ),
+                    _hook(
+                        _dispatch("PreToolUse", "pretooluse-bash-plan-guard"),
+                        _PRETOOLUSE_TIMEOUT_MS,
+                        "Enforce plans locality on shell redirections.",
+                    ),
+                    _hook(
+                        _dispatch("PreToolUse", "pretooluse-eval-guard"),
+                        _PRETOOLUSE_TIMEOUT_MS,
+                        "Flag unsafe dynamic evaluation or deserialization.",
+                    ),
+                ],
+                "sequential": True,
+            },
+            {
+                "matcher": "WriteFile|Edit",
+                "hooks": [
+                    _hook(
+                        _dispatch("PreToolUse", "pretooluse-write"),
+                        _PRETOOLUSE_TIMEOUT_MS,
+                        "Validate write target and content.",
+                    ),
+                    _hook(
+                        _dispatch("PreToolUse", "pretooluse-write-header-guard"),
+                        _PRETOOLUSE_TIMEOUT_MS,
+                        "Inject the authorship header when required.",
+                    ),
+                    _hook(
+                        _dispatch("PreToolUse", "pretooluse-write-plan-guard"),
+                        _PRETOOLUSE_TIMEOUT_MS,
+                        "Enforce plans locality on the target path.",
+                    ),
+                    _hook(
+                        _dispatch("PreToolUse", "pretooluse-dependency-guard"),
+                        _PRETOOLUSE_TIMEOUT_MS,
+                        "Flag unpinned or untrusted dependency additions.",
+                    ),
+                    _hook(
+                        _dispatch("PreToolUse", "pretooluse-eval-guard"),
+                        _PRETOOLUSE_TIMEOUT_MS,
+                        "Flag unsafe dynamic evaluation or deserialization.",
+                    ),
+                ],
+                "sequential": True,
+            },
+        ],
+        "PreCompact": [
+            {
+                "matcher": "*",
+                "hooks": [
+                    _hook(
+                        _dispatch("PreCompact", "precompact"),
+                        _SESSION_TIMEOUT_MS,
+                        "Externalize state before context compression.",
+                    ),
+                ],
+            },
+        ],
+        "PostCompact": [
+            {
+                "matcher": "*",
+                "hooks": [
+                    _hook(
+                        _dispatch("PostCompact", "postcompact"),
+                        _SESSION_TIMEOUT_MS,
+                        "Restore state from durable files after compaction.",
+                    ),
+                ],
+            },
+        ],
+        "Stop": [
+            {
+                "hooks": [
+                    _hook(
+                        _dispatch("Stop", "stop"),
+                        _STOP_TIMEOUT_MS,
+                        "Finalize the session and externalize state.",
+                    ),
+                ],
+            },
+        ],
+    }
+
+
+def materialize_native_config(profile: dict[str, Any]) -> str:
+    """Render the qwen-code native configuration from *profile*.
+
+    Renders the QWEN.md context pointer, the hook wiring, and the profile's MCP
+    inventory into qwen's native ``mcpServers`` surface. Returns a JSON string
+    ready to be written to ``output_path``.
+    """
+    for_harness = coerce_profile(profile).for_harness("qwen-code")
+    config: dict[str, Any] = {
+        "context": {
+            "fileName": "QWEN.md",
+        },
+        "hooks": _qwen_hooks(),
+    }
+    mcp = render_mcp_standard(mcp_servers_for(for_harness))
+    if mcp:
+        config["mcpServers"] = mcp
+    return json.dumps(config, indent=2, ensure_ascii=False) + "\n"

package/src/apothem/harnesses/qwen_code/templates/QWEN.md

@@ -0,0 +1,30 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Apothem — Qwen Code Bootstrap
+
+This file is the user-scope context anchor installed by Apothem for Qwen Code.
+The native JSON settings file remains `~/.qwen/settings.json`; Apothem writes
+that file from the shared profile, registers native hook dispatchers, and
+installs reusable Apothem cohorts into Qwen Code's native discovery surfaces
+where they exist.
+
+## Apothem Cohorts
+
+Resolve Apothem's native Qwen Code cohorts at:
+
+- `~/.qwen/commands/` contains slash commands converted to Qwen Markdown
+  command files.
+- `~/.qwen/skills/` contains reusable SKILL.md skill directories.
+- `~/.qwen/agents/` contains local subagents adapted to Qwen Code's Markdown
+  agent frontmatter.
+
+Resolve Apothem support paths under `~/.qwen/apothem/`:
+
+- `rules/` contains behavioral rules and path-filtered conventions.
+- `templates/` contains plan and report templates.
+- `hooks/` contains hook messages and helper scripts used by the
+  `settings.json` hook commands.
+
+Use the support subtree as reference material when Qwen Code does not expose a
+matching file-based primitive. Do not treat it as a vendor-owned configuration
+namespace.

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

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: MIT
+
+"""Uninstall logic for the qwen-code harness adapter."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from apothem.harnesses._shared import install_driver
+from apothem.harnesses.qwen_code.materializer import materialize_native_config
+
+_HARNESS_NAME: str = "qwen_code"
+
+
+def uninstall(output_path: Path) -> None:
+    """Remove Apothem-managed Qwen Code targets surgically.
+
+    The native ``settings.json`` is rendered by the materializer rather than the
+    manifest, so it is cleaned here: only Apothem's keys (``context``, the hook
+    handlers, the ``mcpServers`` block) are stripped from the parsed operator
+    JSON — operator-added keys and non-Apothem hooks survive — and the file is
+    deleted only when nothing operator-authored remains. The pre-mutation file is
+    copied into the Apothem backup root; no whole-file ``.bak`` sibling is left
+    beside the operator's file. The manifest support subtree is then cleaned
+    child-by-child by the shared driver.
+    """
+    install_driver.surgically_remove_materialized_config(
+        output_path,
+        materialize_native_config({}),
+        install_root=output_path.parent,
+        harness_name=_HARNESS_NAME,
+        apothem_keys=frozenset({"mcpServers"}),
+    )
+    install_driver.run_uninstall(_HARNESS_NAME, harness_root=output_path.parent)

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

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

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

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

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

@@ -0,0 +1,70 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# Trae Standard Convention Pin
+
+## Snapshot
+
+- Snapshot date: 2026-06-25
+- Snapshot note: live re-verification against `docs.trae.ai` surfaced findings: (1) STALENESS — the pin framed Trae's agent surface as absent, but the vendor documents Agents (`docs.trae.ai/ide/agent`, create + manage); (2) skills live in BOTH `.trae/skills/` AND the cross-tool `.agents/skills/` (with `.trae/skills/` winning name collisions) — the pin cited only `.trae/skills/`; (3) `.trae/rules/` supports recursive subfolders up to three levels of nesting. The adapter's rules-only delivery remains a DELIBERATE posture. `.trae/rules/` + `project_rules.md`/`user_rules.md` anchors, AGENTS.md, and MCP (`.trae/mcp.json`, three transport types) all confirmed current. Previous 2026-06-09.
+- Adapter source: `src/apothem/harnesses/trae/`
+- Evidence level: adapter-local projection; no vendor-native UI claim is made here.
+
+## Official Surface Refresh
+
+- Refreshed live 2026-06-09 against the current Trae documentation
+  (`docs.trae.ai`, https://docs.trae.ai/ide/rules). No authority-host move; no
+  immutable version pin is exposed (mutable docs site), so every captured
+  convention carries a no-immutable-source exception.
+- Config-root note: the Trae workspace rules directory is `.trae/rules/`. The
+  vendor anchors are `project_rules.md` (project scope) and `user_rules.md`
+  (user scope). The adapter is project-scope and writes only a dedicated
+  `<project>/.trae/rules/apothem-rules.md` file alongside those anchors; it
+  never clobbers `project_rules.md` or `user_rules.md`.
+- MCP is recognized: `.trae/mcp.json` is operator-owned; the adapter recognizes
+  it but does not author entries. `capabilities.yml` `mcp_servers` and the
+  shared capability matrix were set accordingly.
+- Workspace rules are a `.trae/rules/*.md` directory of Markdown files, not a
+  single file; `layered_context_surface` matches.
+- The vendor documents skills (`.trae/skills/` plus the cross-tool
+  `.agents/skills/`, with `.trae/skills/` winning name collisions), Agents
+  (`docs.trae.ai/ide/agent`), and MCP (`.trae/mcp.json`, three transport types).
+  The adapter delivers only the project rules file and authors none of those
+  cohorts: a DELIBERATE rules-only posture, not a claim the surfaces are absent.
+  Settings and status-lines remain undocumented as adapter-owned file surfaces.
+
+## Recommended Postfix Rendering
+
+- Status: supported as plain text.
+- Mechanism: Apothem emits the literal ` (Recommended)` suffix in the option label. Trae 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
+
+Trae exposes **no vendor plugin or extension install surface** that Apothem
+ships. The adapter is project-scope rules-only: it writes a single merged rules
+file at `<project>/.trae/rules/apothem-rules.md` (alongside, never clobbering,
+the `project_rules.md` / `user_rules.md` anchors) and authors no other cohort.
+There is no standalone-installable bundle; every artifact requires the full
+`apothem install --harness trae --project <path>` engine run.
+
+| Artifact class | Persists standalone? | Mechanism / limit |
+|---|---|---|
+| Rules | No — requires `apothem install` | The merged `apothem-rules.md` (carrying the embedded behavioral mandates) is written only by the engine into the vendor-native `.trae/rules/` directory. Nothing persists before that run. |
+| Commands / Skills / Agents | No — deliberate rules-only posture | Trae documents skills (`.trae/skills/` + `.agents/skills/`) and Agents (`docs.trae.ai/ide/agent`), but the adapter authors none of them (preserve-first rules-only delivery); these cohorts are not materialized for this harness by design. |
+| Hooks / MCP / Settings | No — operator-owned / platform limit | `.trae/mcp.json` (MCP) is operator-owned; the adapter authors no entries. |
+
+Platform limit: Trae ships no marketplace/extension channel, so a plugin-alone
+story does not exist — the merged rules file via `apothem install` is the sole
+persistence surface.

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

@@ -0,0 +1,49 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem harness adapter for trae — project-scope install.
+
+Materializes the apothem rules surface into the operator-supplied
+project root at ``<project>/.trae/rules/apothem-rules.md`` — a dedicated
+apothem rules file inside Trae's documented ``.trae/rules/`` directory per
+https://docs.trae.ai/ide/rules. The vendor anchors ``project_rules.md`` and
+``user_rules.md`` are never clobbered: Apothem writes only its own
+``apothem-rules.md`` file alongside them. Trae's MCP surface
+(``.trae/mcp.json``) and skill surface (``.trae/skills/``) are operator-owned
+and out of apothem's adapter scope.
+
+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.trae.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.trae.install import install as _install
+from apothem.harnesses.trae.install import plan as _plan
+from apothem.harnesses.trae.uninstall import uninstall as _uninstall
+from apothem.harnesses.trae.update import update as _update
+from apothem.harnesses.trae.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(".trae") / "rules" / "apothem-rules.md"
+
+TraeAdapter = make_project_scope_adapter(
+    "trae",
+    error_label="trae",
+    relative_target=_SENTINEL_RELATIVE,
+    install_fn=_install,
+    plan_fn=_plan,
+    uninstall_fn=_uninstall,
+    update_fn=_update,
+    verify_fn=_verify,
+    class_name="TraeAdapter",
+)

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

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: MIT
+
+# Per rules/agent-capability-discipline.md §1 / §3 / §7. Trae
+# ratifies MCP via .trae/mcp.json (operator-owned; the adapter
+# recognizes it but does not author entries). The adapter delivers a
+# single project rules file under .trae/rules/ and does not dispatch
+# sub-agents or author skill/command/hook cohorts.
+
+mcp_servers:
+  - project-scope-.trae/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: ".trae/rules/*.md directory"
+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"). The pinned snapshot catalogs config-materialization
+# surfaces, not the vendor tool surface, so the web-fetch tool is not yet
+# discovered against the pin — discovery-pending per
+# rules/agent-capability-discipline-matrix.md §1.
+web_fetch: "discovery-pending"
+tool_surface_restrictions:
+  - secrets-paths
+  - destructive-shell-ops
+  - network-write-unsigned
+system_prompt_template_path: "templates/apothem-rules.md"
+agent_memory_surface: "n/a"

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

@@ -0,0 +1,38 @@
+# SPDX-License-Identifier: MIT
+
+"""Install logic for the trae harness adapter.
+
+Materializes the apothem Trae rules surface into the operator-supplied
+project root. Trae's canonical rules surface is the project-scope
+Markdown format at ``<project>/.trae/rules/*.md`` (per
+https://docs.trae.ai/ide/rules). The adapter writes a dedicated
+``apothem-rules.md`` file alongside the operator-owned ``project_rules.md``
+and ``user_rules.md`` anchors; the vendor anchors are never clobbered.
+
+The propagation contract is declared in the canonical manifest at
+``src/apothem/lib/propagation-manifest.yaml`` under the ``trae`` key
+(a single ``sentinel_merge`` operation targeting
+``${PROJECT_ROOT}/.trae/rules/apothem-rules.md``) 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 = "trae"
+
+install = make_project_scope_install(
+    _HARNESS_NAME,
+    error_message="trae adapter requires --project <path>; CLI must thread it through",
+)
+
+plan = make_project_scope_plan(_HARNESS_NAME)