@ahmed-g-gad/apothem 0.1.1

package/bin/apothem.mjs

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// SPDX-License-Identifier: MIT
+
+// npx launcher for the apothem CLI.
+//
+// Locates a Python 3.10+ interpreter, points PYTHONPATH at the package's
+// self-contained source tree (vendored dependencies first, then the engine),
+// and executes `python -m apothem` with the caller's arguments. The engine
+// requires the `click` and `rich` Python packages to be importable; every
+// other runtime dependency ships vendored inside the tree.
+
+import { spawnSync } from "node:child_process";
+import { delimiter, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const MIN_PYTHON = [3, 10];
+
+const packageRoot = fileURLToPath(new URL("..", import.meta.url));
+const vendorPath = join(packageRoot, "src", "apothem", "_vendor");
+const sourcePath = join(packageRoot, "src");
+
+const versionProbe =
+  "import sys; raise SystemExit(0 if sys.version_info[:2] >= " +
+  `(${MIN_PYTHON[0]}, ${MIN_PYTHON[1]}) else 1)`;
+
+/** Interpreter candidates, ordered; each is [command, ...leading args]. */
+const candidates = [];
+if (process.env.APOTHEM_PYTHON) {
+  candidates.push([process.env.APOTHEM_PYTHON]);
+}
+candidates.push(["python3"], ["python"], ["py", "-3"]);
+
+function probe(candidate) {
+  const [command, ...lead] = candidate;
+  const result = spawnSync(command, [...lead, "-c", versionProbe], {
+    stdio: "ignore",
+  });
+  return result.status === 0;
+}
+
+const interpreter = candidates.find(probe);
+if (!interpreter) {
+  process.stderr.write(
+    "apothem: Python " +
+      `${MIN_PYTHON[0]}.${MIN_PYTHON[1]}+` +
+      " is required but no suitable interpreter was found.\n" +
+      "Install Python from https://www.python.org/downloads/ or point the\n" +
+      "APOTHEM_PYTHON environment variable at an interpreter, then retry.\n",
+  );
+  process.exit(1);
+}
+
+const [command, ...lead] = interpreter;
+const env = {
+  ...process.env,
+  PYTHONPATH: [vendorPath, sourcePath, process.env.PYTHONPATH]
+    .filter(Boolean)
+    .join(delimiter),
+};
+
+const depsProbe = spawnSync(command, [...lead, "-c", "import click, rich"], {
+  stdio: "ignore",
+  env,
+});
+if (depsProbe.status !== 0) {
+  process.stderr.write(
+    "apothem: missing runtime dependencies: click rich\n" +
+      "Make the click and rich Python packages importable for " +
+      `'${command}', then retry.\n`,
+  );
+  process.exit(1);
+}
+
+const run = spawnSync(command, [...lead, "-m", "apothem", ...process.argv.slice(2)], {
+  stdio: "inherit",
+  env,
+});
+process.exit(run.status ?? 1);

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@ahmed-g-gad/apothem",
+  "version": "0.1.1",
+  "description": "Host-agnostic AI-harness configuration manager: one shared profile materializes native configs for seventeen AI assistant harnesses, syncing rules, skills, slash-commands, hooks, and MCP servers behind a conformity governance gate and signed releases.",
+  "keywords": [
+    "agent",
+    "agnostic",
+    "ai",
+    "ai-assistant",
+    "ai-harness",
+    "antigravity",
+    "apothem",
+    "automation",
+    "claude-code",
+    "code-assistant",
+    "codebuddy",
+    "codex",
+    "config-manager",
+    "configuration-management",
+    "conformity",
+    "cursor",
+    "developer-tools",
+    "dotfiles",
+    "ecosystem",
+    "gemini-cli",
+    "github-copilot",
+    "glm",
+    "governance",
+    "harness",
+    "hermes",
+    "hooks",
+    "host-agnostic",
+    "kimi-code",
+    "kiro",
+    "llm",
+    "mcp",
+    "open-claw",
+    "opencode",
+    "orchestration",
+    "qwen-code",
+    "skills",
+    "slash-commands",
+    "trae",
+    "windsurf",
+    "zed"
+  ],
+  "homepage": "https://apothem.ahmedgad.com",
+  "bugs": "https://github.com/Ahmed-G-Gad/apothem/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ahmed-G-Gad/apothem.git"
+  },
+  "license": "MIT",
+  "author": "Ahmed G. Gad <me@ahmedgad.com> (https://github.com/Ahmed-G-Gad)",
+  "type": "module",
+  "bin": {
+    "apothem": "bin/apothem.mjs"
+  },
+  "files": [
+    "bin/",
+    "src/apothem/",
+    "pyproject.toml",
+    "LICENSE",
+    "LICENSES/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/pyproject.toml

@@ -0,0 +1,347 @@
+# SPDX-License-Identifier: MIT
+
+[build-system]
+requires      = ["setuptools>=68.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "apothem"
+version = "0.1.1"
+description = "Host-agnostic AI-harness configuration manager: one shared profile materializes native configs for seventeen AI assistant harnesses, syncing rules, skills, slash-commands, hooks, and MCP servers behind a conformity governance gate and signed releases."
+requires-python = ">=3.10"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE", "LICENSES/MIT.txt"]
+dependencies = [
+    # Pinned exactly: the CLI shell-completion scripts are Click-generated, and
+    # the byte-identical behavior-diff golden (completion-fish.json) is only
+    # stable against a fixed Click — 8.4.1 and 8.4.2 emit different `string
+    # split` delimiters. Relax once the behavior-diff oracle normalizes the
+    # Click-generated completion blocks.
+    "click==8.4.2",
+    "rich>=15.0.0",
+    "pyyaml>=6.0.3",
+    "jsonschema>=4.26.0",
+]
+authors = [
+    { name = "Ahmed G. Gad", email = "me@ahmedgad.com" },
+]
+maintainers = [
+    { name = "Ahmed G. Gad", email = "me@ahmedgad.com" },
+]
+keywords = ["agent", "agnostic", "ai", "ai-assistant", "ai-harness", "antigravity", "apothem", "automation", "claude-code", "code-assistant", "codebuddy", "codex", "config-manager", "configuration-management", "conformity", "cursor", "developer-tools", "dotfiles", "ecosystem", "gemini-cli", "github-copilot", "glm", "governance", "harness", "hermes", "hooks", "host-agnostic", "kimi-code", "kiro", "llm", "mcp", "open-claw", "opencode", "orchestration", "qwen-code", "skills", "slash-commands", "trae", "windsurf", "zed"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "Operating System :: OS Independent",
+    "Operating System :: POSIX :: Linux",
+    "Operating System :: MacOS",
+    "Operating System :: Microsoft :: Windows",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Software Development",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Quality Assurance",
+    "Topic :: Utilities",
+    "Environment :: Console",
+]
+
+[project.urls]
+# Homepage points at the marketing landing of the comprehensive project
+# website. Documentation points at the website's documentation section
+# (day-to-day user guides). Source / Issues / Discussions / Changelog /
+# Security route at the canonical GitHub surfaces.
+Homepage      = "https://apothem.ahmedgad.com/"
+Documentation = "https://apothem.ahmedgad.com/docs/usage/"
+Reference     = "https://apothem.ahmedgad.com/docs/reference/"
+Architecture  = "https://apothem.ahmedgad.com/docs/architecture/"
+Repository    = "https://github.com/ahmed-g-gad/apothem"
+Issues        = "https://github.com/ahmed-g-gad/apothem/issues"
+Discussions   = "https://github.com/ahmed-g-gad/apothem/discussions"
+Changelog     = "https://github.com/ahmed-g-gad/apothem/blob/main/CHANGELOG.md"
+Security      = "https://github.com/ahmed-g-gad/apothem/security"
+Brand         = "https://apothem.ahmedgad.com/docs/brand/"
+
+# Console scripts are intentionally absent: apothem installs as a per-harness
+# plugin and runs directly on the system Python interpreter. The engine CLI
+# is invoked through the module surface (`python -m apothem`), and harness
+# hook entries invoke the materialized dispatcher and conformity gate by
+# absolute script path under the harness root, so no console-script shims
+# or importable site-packages install are required on the host.
+
+[project.entry-points."apothem.harnesses"]
+claude-code    = "apothem.harnesses.claude_code:ClaudeCodeAdapter"
+cursor         = "apothem.harnesses.cursor:CursorAdapter"
+gemini-cli     = "apothem.harnesses.gemini_cli:GeminiCliAdapter"
+github-copilot = "apothem.harnesses.github_copilot:GitHubCopilotAdapter"
+codex          = "apothem.harnesses.codex:CodexAdapter"
+windsurf       = "apothem.harnesses.windsurf:WindsurfAdapter"
+opencode       = "apothem.harnesses.opencode:OpenCodeAdapter"
+antigravity    = "apothem.harnesses.antigravity:AntigravityAdapter"
+open-claw      = "apothem.harnesses.open_claw:OpenClawAdapter"
+hermes         = "apothem.harnesses.hermes:HermesAdapter"
+qwen-code      = "apothem.harnesses.qwen_code:QwenCodeAdapter"
+kimi-code      = "apothem.harnesses.kimi_code:KimiCodeAdapter"
+codebuddy      = "apothem.harnesses.codebuddy:CodeBuddyAdapter"
+kiro           = "apothem.harnesses.kiro:KiroAdapter"
+trae           = "apothem.harnesses.trae:TraeAdapter"
+zed            = "apothem.harnesses.zed:ZedAdapter"
+glm            = "apothem.harnesses.glm:GlmAdapter"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Single source of truth for the project version: the ``[project] version``
+# field above (per ``rules/dynamism.md`` §f + §Single-Source). Every other
+# version-bearing surface derives from it dynamically: the runtime
+# ``apothem.__version__`` resolves it via ``importlib.metadata.version`` at
+# import time, README badges via the shields.io GitHub-release endpoint, and
+# the docs site via its build-time export. A prior ``dynamic = ["version"]`` + ``attr =
+# "apothem.__version__"`` wiring was circular (the build attribute pointed at
+# a runtime ``importlib.metadata`` lookup that is unresolvable in an isolated
+# build env, producing ``0.0.0+unknown`` artifacts).
+
+[tool.setuptools.package-data]
+# Bundle non-Python schema and fixture files with the wheel so runtime
+# consumers can resolve them via importlib.resources regardless of the
+# install location.
+"apothem.schemas"     = ["*.json", "*.yaml", "*.txt", "*.md"]
+# Hook library ships cross-platform shell stubs alongside the Python
+# dispatcher (bootstrap.{sh,ps1}, find-python.{sh,ps1}, find-pwsh.{sh,ps1})
+# plus the per-event Markdown context fixtures consumed by the dispatcher.
+"apothem.hooks"       = ["lib/*.sh", "lib/*.ps1", "messages/*.md"]
+# Statusline renderer ships the shell shims plus the conformity-posture
+# data file and the operator-facing reference Markdown.
+"apothem.statuslines" = ["*.sh", "*.ps1", "*.md", "*.json"]
+# Shared lib package ships the propagation manifest YAML so harness adapters
+# can load it via importlib.resources regardless of install location.
+"apothem.lib"         = ["*.yaml"]
+# Vendored runtime data (critical C5). The jsonschema validator loads the
+# meta-schemas at runtime to validate the profile schema: the per-draft
+# metaschema.json AND the EXTENSIONLESS vocabulary files under
+# schemas/<draft>/vocabularies/ (e.g. .../draft202012/vocabularies/core). Both
+# the recursive `schemas/**/*` glob and these globs reach the non-package
+# `schemas/` subtree from its parent package, so a built wheel/sdist ships them
+# — without them a manual `pip install <wheel>` crashes on first profile
+# validation. Upstream LICENSE files and typing stubs ship alongside for
+# license compliance and type completeness.
+"apothem._vendor"                           = ["*.LICENSE", ".keep"]
+"apothem._vendor.jsonschema_specifications" = ["schemas/**/*"]
+"apothem._vendor.jsonschema"                = ["benchmarks/**/*.json"]
+"apothem._vendor.attr"                      = ["*.pyi", "py.typed"]
+"apothem._vendor.attrs"                     = ["*.pyi", "py.typed"]
+"apothem._vendor.referencing"               = ["*.pyi", "py.typed"]
+# Harness adapter packages ship registry payloads beside their Python modules:
+# templates for render/write sources, capabilities.yml for the capability
+# matrix, and STANDARD-CONVENTION-PIN.md for convention evidence. These MUST
+# bundle in both wheel and sdist artifacts so install, verify, docs, and
+# release-readiness checks operate from the same registry-backed payload set.
+"apothem.harnesses.antigravity"    = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.claude_code"    = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.codex"          = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.cursor"         = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.gemini_cli"     = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.github_copilot" = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.hermes"         = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md"]
+"apothem.harnesses.open_claw"      = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md"]
+"apothem.harnesses.opencode"       = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md"]
+"apothem.harnesses.qwen_code"      = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.kimi_code"      = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.windsurf"       = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.codebuddy"      = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.kiro"           = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.trae"           = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.zed"            = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+"apothem.harnesses.glm"            = ["capabilities.yml", "STANDARD-CONVENTION-PIN.md", "templates/*"]
+# The top-level content directories — agents, slash-commands, behavioral
+# rules, skills, output styles, and plan-suite templates — are Markdown
+# payloads with no __init__.py, so they bundle under the `apothem`
+# package key with directory-relative globs rather than as sub-packages.
+"apothem"             = [
+    # PEP 561 inline-type marker: apothem is type-checked under mypy --strict,
+    # so the wheel/sdist ships py.typed to surface its types to importers.
+    "py.typed",
+    "agents/*.md",
+    "commands/*.md",
+    "commands/**/*.md",
+    "rules/*.md",
+    "skills/**/*.md",
+    "output-styles/*.md",
+    "templates/*.md",
+]
+
+[project.optional-dependencies]
+dev = [
+    "ruff>=0.15.14",
+    "mypy>=2.1.0",
+    "types-PyYAML>=6.0.12.20260518",
+    "types-jsonschema>=4.26.0.20260518",
+    "pytest>=9.0.3",
+    "pytest-cov>=7.1.0",
+    "pytest-xdist>=3.8.0",
+    # Hypothesis ratifies the property-test surface that feeds the OpenSSF
+    # Scorecard Fuzzing check. Property tests at tests/property/ exercise
+    # invariants (round-trip, idempotence, schema-validity) across
+    # auto-generated inputs across the search space.
+    "hypothesis>=6.152.9",
+]
+security = [
+    "bandit[toml]>=1.9.4",
+    "pip-audit>=2.10.0",
+]
+release = [
+    "build>=1.5.0",
+    "twine>=6.2.0",
+]
+
+[tool.bandit]
+# Project-wide bandit policy. Skips the heuristic findings whose
+# patterns are intrinsic to admin-tooling work and not actual security
+# concerns: assert statements (pytest idiom), subprocess calls with
+# locally-constructed argv, partial-path executable lookup (`git`,
+# `python`), fail-open try/except/pass in the dispatcher.
+exclude_dirs = ["tests", ".plans", ".apothem", "projects", "memory", "examples", "backups", "src/apothem/_vendor", "*/_vendor/*"]
+skips = [
+    "B101",  # assert_used — covered by ruff S101 + per-file ignores
+    "B110",  # try_except_pass — fail-open dispatcher pattern (intentional)
+    "B112",  # try_except_continue — fail-open per-matcher isolation (intentional, mirrors B110)
+    "B404",  # blacklist_subprocess_import — admin tooling needs subprocess
+    "B603",  # subprocess_without_shell_equals_true — argv is locally-constructed
+    "B607",  # start_process_with_partial_path — `git`, `python` resolved by PATH
+]
+
+[tool.ruff]
+line-length = 88
+target-version = "py310"
+extend-exclude = [
+    "backups",
+    "cache",
+    "debug",
+    "downloads",
+    "file-history",
+    "ide",
+    ".plans",
+    ".apothem",
+    "plugins",
+    "projects",
+    "session-env",
+    "sessions",
+    "shell-snapshots",
+    "statsig",
+    "todos",
+    "tests/conformity-scenarios/fixtures",
+    # The install_driver behavior-diff golden corpus is a frozen, generated
+    # oracle (rendered native config copies + ledger/plan snapshots); it is
+    # captured verbatim, not apothem-authored source, so it is not linted.
+    "tests/fixtures/behavior-diff",
+    # Vendored upstream trees ship verbatim into the plugin runtime; they are
+    # not apothem-authored source, so they are excluded from linting.
+    "src/apothem/_vendor",
+]
+
+[tool.ruff.lint]
+select = ["E", "F", "W", "I", "UP", "B", "SIM", "N", "S", "C4", "ANN", "PT", "FA", "PTH", "RET", "RUF"]
+ignore = ["E501"]
+
+[tool.ruff.lint.per-file-ignores]
+# Pytest's expected idiom: assertions are the test harness's primary
+# verification mechanism, so suppress the security-rule that flags
+# them as "use of assert". The S603 entry covers test-side subprocess
+# invocations of locally-resolved scripts via sys.executable; the
+# argv vectors are constructed in-test from fixed paths. The S607 entry
+# covers test-side `git` invocations resolved via PATH (the no-global-
+# plans-grep self-tests use `git init` / `git config` / `git add` /
+# `git commit` against ephemeral tmp_path repos).
+"tests/**/*.py" = ["S101", "S603", "S607", "ANN001", "ANN002", "ANN201", "ANN202", "N802"]
+# Conformity fixtures intentionally exhibit the patterns the
+# corresponding mechanical greps detect (bare-except, hard-coded
+# sentinel literals, fail-open swallow). The fixture files are
+# the test surface for the validators; the rules are observed
+# in the fixture's pass/fail counterparts, not authored in
+# real source.
+"tests/conformity/**" = ["E722", "S105", "S110", "F841", "BLE001"]
+# The hook dispatcher and emit_hook_context.py manipulate sys.path
+# before importing local helpers, so import-sort and module-import-
+# at-top rules cannot apply uniformly. The fail-open try/except/pass
+# is intentional per the dispatcher's contract: hook context is
+# advisory and must never block the underlying tool call.
+"src/apothem/hooks/dispatch.py"          = ["E402", "I001", "S110"]
+"src/apothem/hooks/emit_hook_context.py" = ["E402", "I001"]
+# Tooling scripts invoke subprocesses with controlled, internally-
+# constructed argument vectors. The S603 / S607 security rules
+# generalize to "untrusted input" but the inputs here are always
+# locally-derived paths and python interpreter discovery results.
+"scripts/dev/audit_all.py"                                    = ["S603"]
+"scripts/dev/auto_update.py"                                  = ["S603", "S607"]
+"scripts/dev/chaos_pass.py"                                   = ["S603"]
+"src/apothem/conformity/production_ready_pr_grep.py"   = ["S603"]
+"src/apothem/conformity/semver_stability_grep.py"      = ["S603", "S607"]
+"src/apothem/conformity/agents_md_coverage_grep.py"    = ["S603", "S607"]
+# `_PASS` is a label string ("[PASS]"), not a credential. The
+# heuristic security-rule pattern-matches on the variable name.
+"src/apothem/lib/reporter.py" = ["S105"]
+
+[tool.ruff.format]
+quote-style = "double"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+python_files = ["test_*.py"]
+# import-mode = importlib + consider_namespace_packages lets sibling test
+# directories reuse the same test_NAME.py basenames (e.g., the validator
+# self-tests at tests/conformity/file-header/ and the injector self-tests
+# at tests/scripts/inject-header/ both ship a test_exempt_*.py). Without
+# consider_namespace_packages the duplicate basenames collide under
+# parallel (-n auto) collection and crash an xdist worker.
+addopts = "-ra --strict-markers --import-mode=importlib -n auto"
+consider_namespace_packages = true
+
+[tool.mypy]
+python_version = "3.10"
+strict = true
+files = ["src/apothem/cli", "src/apothem/harnesses", "src/apothem/lib", "src/apothem/conformity"]
+mypy_path = "src"
+explicit_package_bases = true
+exclude = ["tests/conformity", "src/apothem/_vendor"]
+
+# Tests use pytest fixtures and dynamic monkeypatching; strict typing would
+# produce excessive false positives without adding safety. We still type-check
+# them with relaxed settings so obvious regressions are caught.
+[[tool.mypy.overrides]]
+module = "tests.*"
+disallow_untyped_defs = false
+disallow_incomplete_defs = false
+check_untyped_defs = true
+warn_return_any = false
+
+[tool.coverage.run]
+# Engine-scoped: the runtime surface the tool actually executes (CLI + the 15
+# harness adapters + the lib core + the hook/statusline runtime). Conformity
+# matchers and the audit/reference dev-tools are deliberately out of scope so the
+# coverage figure is the honest engine signal, not one inflated by the
+# heavily-fixtured conformity self-test corpora.
+source = [
+    "src/apothem/cli",
+    "src/apothem/harnesses",
+    "src/apothem/lib",
+    "src/apothem/hooks",
+    "src/apothem/statuslines",
+]
+branch = true
+omit = [
+    "*/benchmarks/*",
+    "*/_vendor/*",
+]
+
+[tool.coverage.report]
+fail_under = 80
+show_missing = true
+exclude_lines = [
+    "raise NotImplementedError",
+    "if TYPE_CHECKING:",
+    "\\.\\.\\.",
+]

package/src/apothem/README.md

@@ -0,0 +1,52 @@
+<!-- SPDX-License-Identifier: MIT -->
+
+# apothem
+
+> **Role.** `apothem` is a harness-agnostic AI-configuration manager. It maintains one shared corpus of rules, agents, commands, skills, output-styles, and templates, and materializes that corpus into each AI tool's native configuration directory through a per-harness adapter. Author the conventions once; `apothem` propagates them to every harness the operator runs.
+
+## Package Map
+
+### Code subpackages
+
+| Child | Holds |
+|-------|-------|
+| [`audit/`](audit/) | Inventory and drift scanners that map the ecosystem and surface staleness, leakage, and convention findings. |
+| [`benchmarks/`](benchmarks/) | Per-class performance benchmark drivers (hooks, tests, agents, ecosystem sweep). |
+| [`cli/`](cli/) | The `apothem` command-line surface, shared flags, JSON formatter, propagation loader, and shell completions. |
+| [`conformity/`](conformity/) | Pre-emission conformity validators — the gate orchestrator plus mechanical `*_grep` matchers and the link checker. |
+| [`harnesses/`](harnesses/) | Per-harness adapter subpackages implementing the `HarnessAdapter` protocol — one per supported AI tool. |
+| [`hooks/`](hooks/) | The hook dispatcher, bootstrap stubs, event vocabulary, and per-event Markdown context messages. |
+| [`lib/`](lib/) | Shared internal helpers (frontmatter probing, materializer building blocks, parallel sweep, reporting). |
+| [`statuslines/`](statuslines/) | The conformity-posture statusline renderer plus shell shims and reference docs. |
+
+### Content / asset directories
+
+| Child | Holds |
+|-------|-------|
+| `agents/` | Persistent agent definitions (mission, deliverable, constraints) materialized into harness agent dirs. |
+| `commands/` | Slash-command definitions — the `/plan` pipeline and the audit/review commands. |
+| `rules/` | The shared behavioral rule corpus (always-on and path-filtered `.md` rules). |
+| `skills/` | Folder skills, each with a `SKILL.md` entry point. |
+| `output-styles/` | Output-style definitions controlling response shape. |
+| `templates/` | Scaffolding templates consumed by the planning workflow and renderers. |
+| `schemas/` | Schema fixtures used by validators and tests. |
+
+### Package files
+
+| File | Holds |
+|------|-------|
+| `__init__.py` | Package marker and version surface for `apothem`. |
+| `__main__.py` | Module entry point — `python -m apothem` dispatches to the [`cli/`](cli/) command surface. |
+
+## Conventions
+
+- Code subpackages are importable Python modules; content directories are corpora the harness adapters propagate.
+- The `claude_code` harness consumes the full surface (code directories travel with the bundled plugin tree, convention directories flatten into the harness config root); the other harnesses receive a materialized native config and, where the native format differs, converted cohorts per their adapter.
+- The code-vs-content split is load-bearing: an adapter subpackage in `harnesses/` is named by its catalog slug, never privileged by a brand phrase, and content corpora carry no executable Python.
+
+## Operating in this folder
+
+- **Self-contained run model.** The engine runs from source via `PYTHONPATH=src python -m apothem ...` with its dependencies vendored under `_vendor/`; do not assume an installed entry point when verifying changes here. `_vendor/` is a vendored tree an agent does not hand-edit.
+- Add or modify code inside the owning subpackage rather than at this root; add corpus artifacts inside the owning content directory.
+- After any change, validate with `python -m ruff check . --fix`, then `python -m mypy src/apothem/cli/ src/apothem/harnesses/` (strict scope is `cli` + `harnesses`), then `python -m pytest`, then `python -m apothem.conformity.gate --all .`.
+- A new harness adapter touches several coupled surfaces beyond its subpackage (registry, manifest, golden fixtures, profile schema, tests) — consult `harnesses/README.md` before adding one.

package/src/apothem/__init__.py

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+
+"""Apothem — host-agnostic AI harness configuration manager."""
+
+from __future__ import annotations
+
+import importlib.metadata
+import re
+from pathlib import Path
+
+#: How many ancestor directories to inspect for the source tree's manifest.
+#: ``src/apothem/__init__.py`` sits two levels below the tree root, so three
+#: levels covers the repository checkout, the npm package tree, and one
+#: nesting layer of slack without ever walking into unrelated projects.
+_MANIFEST_SEARCH_DEPTH = 3
+
+
+def _version_from_source_tree() -> str | None:
+    """Read the version from the ``pyproject.toml`` co-located with this tree.
+
+    The self-contained runtime ships its source tree (a repository checkout,
+    the npm package, or an installer-managed copy) without installed package
+    metadata, so the co-located manifest is the authoritative version source.
+    The manifest is accepted only when it declares ``name = "apothem"`` so a
+    foreign ``pyproject.toml`` higher up the filesystem is never captured.
+
+    Returns:
+        The declared version, or ``None`` when no apothem manifest is found
+        within the bounded ancestor walk.
+    """
+    for parent in Path(__file__).resolve().parents[:_MANIFEST_SEARCH_DEPTH]:
+        candidate = parent / "pyproject.toml"
+        if not candidate.is_file():
+            continue
+        try:
+            text = candidate.read_text(encoding="utf-8")
+        except OSError:
+            return None
+        if re.search(r'^\s*name\s*=\s*["\']apothem["\']', text, flags=re.MULTILINE):
+            match = re.search(
+                r'^\s*version\s*=\s*["\']([^"\']+)["\']', text, flags=re.MULTILINE
+            )
+            return match.group(1) if match else None
+        return None
+    return None
+
+
+def _resolve_version() -> str:
+    """Resolve the package version: source tree first, then installed metadata.
+
+    Precedence: the co-located ``pyproject.toml`` (the self-contained runtime's
+    single source of truth, also authoritative for editable checkouts where
+    stale installed metadata can shadow the tree), then ``importlib.metadata``
+    for wheel installs, then the explicit unknown sentinel.
+    """
+    declared = _version_from_source_tree()
+    if declared is not None:
+        return declared
+    try:
+        return importlib.metadata.version(__name__)
+    except importlib.metadata.PackageNotFoundError:
+        return "0.0.0+unknown"
+
+
+__version__ = _resolve_version()
+__author__ = "Ahmed G. Gad"

package/src/apothem/__main__.py

@@ -0,0 +1,28 @@
+# SPDX-License-Identifier: MIT
+
+"""Module entry point: ``python -m apothem``.
+
+``python -m apothem`` is the canonical invocation surface — apothem ships
+no ``[project.scripts]`` console-script shim. The npm shim
+(``npx @ahmed-g-gad/apothem``), the Claude Code plugin, and the one-shot
+installers all run this same module surface; the installers additionally
+place a thin ``apothem`` shell shim on ``PATH`` that forwards here. This
+module makes the package directly executable so a fresh checkout, CI
+sandbox, or isolated virtualenv resolves the identical entry point with
+nothing installed.
+"""
+
+from apothem.cli import _configure_stdio, main
+
+if __name__ == "__main__":
+    # Force UTF-8 stdio (Windows) before Click parses anything. Click emits
+    # ``--help`` / ``--version`` from eager-option handling, and usage errors
+    # from argument parsing, *before* the group callback body runs — so a
+    # reconfigure inside that callback (apothem/cli/__init__.py) never reaches
+    # those surfaces. Doing it here, at the invocation entry and never at
+    # import (this block runs only under ``python -m apothem``), makes every
+    # Click surface inherit UTF-8 on a legacy-codepage host when stdout is a
+    # pipe or redirect. The group-callback call remains as defense-in-depth
+    # for a direct ``apothem.cli.main`` import that bypasses this entry.
+    _configure_stdio()
+    raise SystemExit(main())