metaensemble 0.2.0__tar.gz

metaensemble-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MetaEnsemble contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

metaensemble-0.2.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: metaensemble
+Version: 0.2.0
+Summary: A typed runtime for ensembles of cognitive agents
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jsonschema>=4.20
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-cov>=4.0; extra == "test"
+Requires-Dist: bandit>=1.7; extra == "test"
+Requires-Dist: ruff>=0.5; extra == "test"
+Requires-Dist: radon>=6.0; extra == "test"
+Requires-Dist: coverage>=7.0; extra == "test"
+Requires-Dist: build>=1.0; extra == "test"
+Requires-Dist: tomli>=2.0; python_version < "3.11" and extra == "test"
+Provides-Extra: quality
+Requires-Dist: bandit>=1.7; extra == "quality"
+Requires-Dist: ruff>=0.5; extra == "quality"
+Requires-Dist: radon>=6.0; extra == "quality"
+Requires-Dist: coverage>=7.0; extra == "quality"
+Requires-Dist: pip-audit>=2.6; extra == "quality"
+Dynamic: license-file
+
+# MetaEnsemble
+
+**Stable identity, typed contracts, and observable runs for ensembles of cognitive agents.**
+
+MetaEnsemble gives every agent a persistent ID, every handoff a schema-validated contract, and every run an entry in an append-only ledger. Multiple agents instantiated from one Role specification execute in parallel. Identities survive across sessions. Token-efficient by construction.
+
+**v0.2.0 status:** feedback-first release. The software records and gates local agent work, but measured quality-per-token improvements remain a product hypothesis until the live evaluation set is larger and fully baseline-comparable. See [SYSTEM-CARD.md](./docs/SYSTEM-CARD.md).
+
+---
+
+## Why MetaEnsemble exists
+
+Coordinating multiple cognitive agents tends to fail in the same three places:
+
+1. **No stable identity.** Each agent invocation is anonymous. No way to say "follow up with the same Executor next week."
+2. **No typed handoffs.** Context passes between agents as free-form prose. Every receiver re-derives state by searching, re-reading, re-grepping.
+3. **No observability.** Token spend, model choice, outcome — nothing captured per run. Optimization is guesswork.
+
+MetaEnsemble fixes all three at the substrate, not as features. Every primitive in the system carries an ID, every transport is schema-validated, every execution lands in the Ledger.
+
+---
+
+## What MetaEnsemble gives you
+
+- **Persistent identities.** Every Executor has a UUIDv7 and a short alias (`arch-7b3`). Resume any past Executor across sessions with `/relaunch arch-7b3`.
+- **Typed contracts.** Handoffs travel as YAML Manifests validated against a JSON Schema. Inter-Executor messages travel as terse JSON Briefs. No prose context-injection, no re-search on the receiving side.
+- **Observable runs.** Append-only Ledger (SQLite live, JSONL mirror for replay) records every Run with token cost, requested model tier, runtime-observed model when available, outcome, and links to its Deliverable.
+- **MetaEnsemble dispatch.** Spawn N Executors from one Role spec for parallel hypothesis exploration, consensus review, or fan-out implementation. Default is N=1; multi-instance is opt-in and currently validated at the planning/protocol layer.
+- **Cross-session continuity.** An Executor's identity is a Ledger row, not a live process. Relaunch is cheap (last Brief + last Deliverable summary) by default, deep (`--full`) when needed.
+- **Two-channel design.** Machine-to-machine traffic (Briefs) stays terse and structured. Human-facing output (Deliverables) stays full English. Same Run produces both. No "compression tier" knob to misset.
+- **Threshold-based cost gating.** The Coordinator auto-decides cheap, reversible work. It surfaces only the calls that warrant Principal judgment, in a structured options table — never as conversational back-and-forth.
+
+---
+
+## Primitives
+
+| Term | Shape | What it is |
+|---|---|---|
+| **Principal** | The human running the system | The person who dispatches work and approves above-threshold decisions. Maps to the IAM Principal concept. |
+| **Coordinator** | The main agent in the active session | Plans Tasks, dispatches Executors, validates contracts, synthesizes Deliverables. Maps to the Kafka / ZooKeeper / Cassandra coordinator pattern. |
+| **Role** | Markdown file with frontmatter spec | The Job Description. Declarative, versioned. Maps to a Kubernetes Deployment spec or IAM Role. |
+| **Executor** | Row in the registry, identified by UUIDv7 + alias | A live instance of a Role. Multiple per Role per Task. Survives sessions. Maps to a Spark Executor or K8s Pod. |
+| **Task** | Unit of work | What the Principal asks the ensemble to do. Has dependencies, expected deliverables, budget. |
+| **Run** | Row in the Ledger | One execution attempt by one Executor for one Task. Maps to an MLflow run. |
+| **Brief** | Schema-validated JSON | Wire-format message between Executors. Terse, machine-targeted. |
+| **Manifest** | Schema-validated YAML | Handoff contract. Typed pointers to files, line ranges, schemas, prior runs. Maps to a dbt or OpenAPI manifest. |
+| **Deliverable** | Markdown report | Human-readable output. English prose. Institutional memory. |
+| **Ledger** | SQLite + JSONL mirror | Append-only log of every Run. Queryable, replayable. Maps to MLflow tracking. |
+| **Registry** | View over the Ledger + Executor table | Current-state snapshot. Live Executors, open Tasks, dependencies. Maps to a service-mesh control-plane view. |
+| **Dispatch** | Verb / slash command | The act of launching N Executors of a Role for a Task. |
+
+---
+
+## High-level flow
+
+```
+                ┌─────────────────────┐
+                │      Principal      │  (you)
+                └──────────┬──────────┘
+                           │ intent
+                ┌──────────▼──────────┐
+                │     Coordinator     │  plans, dispatches, synthesizes
+                └─────┬────────┬──────┘
+                      │        │
+        ┌─────────────┘        └───────────┐
+        │                                  │
+   ┌────▼─────────┐                ┌───────▼──────┐
+   │ Role: backend│                │ Role: review │
+   │  spec file   │                │  spec file   │
+   └────┬─────────┘                └───────┬──────┘
+        │  dispatch N=2                    │  dispatch N=3
+   ┌────┴────┐                       ┌─────┼─────┐
+   ▼         ▼                       ▼     ▼     ▼
+ ┌─────┐  ┌─────┐                  ┌────┐┌────┐┌────┐
+ │be-1 │  │be-2 │                  │rv-1││rv-2││rv-3│
+ └──┬──┘  └──┬──┘                  └─┬──┘└─┬──┘└─┬──┘
+    │ Brief  │ Brief                 │     │     │
+    ▼        ▼                       ▼     ▼     ▼
+ ┌────────────────────────────────────────────────┐
+ │              Ledger (SQLite + JSONL)           │
+ └────────────────────────────────────────────────┘
+                          │
+                          ▼
+                  ┌──────────────┐
+                  │ Deliverables │  English, for humans
+                  └──────────────┘
+```
+
+A single `/dispatch` produces N Executors across one or more Roles. Each Executor emits a Brief downstream and a Deliverable upstream. Every Run is logged. The Principal sees Deliverables and the standup view; never the wire traffic.
+
+---
+
+## Why two channels
+
+A single Run produces two artifacts:
+
+- The **Brief** is what the next Executor receives. Terse JSON. Schema-validated. Machine-targeted. Cheap to emit, cheap to parse.
+- The **Deliverable** is what you, the Principal, read. Full English. Prose. Institutional memory.
+
+These are not intensity tiers. They are different artifacts for different audiences, produced together. The receiving Executor does not parse English; the human does not parse JSON. Each gets the format that earns its place.
+
+---
+
+## How it runs
+
+MetaEnsemble runs entirely on your laptop. Clone the repo, drop the conventions into your local agent runtime configuration, and dispatch. No servers, no cloud accounts, no hosting. Your Ledger, your Executors, your Briefs all live on your filesystem. State is portable: copy the repo and the state directory, and MetaEnsemble runs anywhere the agent runtime is installed.
+
+---
+
+## Adopting MetaEnsemble in your project
+
+MetaEnsemble is project-agnostic by design. Three layers, with project-specific knowledge confined to the project layer:
+
+```
+metaensemble/                           # shipped with MetaEnsemble; project-agnostic
+~/.metaensemble/                # per-engineer preferences; the vendored runtime (runtime/, runtime-versions/); the runner at runtime/bin/me-run
+<your-project>/.metaensemble/   # project-specific state, manifests, and install decisions
+```
+
+The adoption flow has two layers, asked separately:
+
+```bash
+metaensemble setup               # interactive wizard: picks a project, asks for layout, runs the two steps below
+```
+
+The wizard lists every Claude Code project on this machine, lets you pick one, asks once for the layout (namespaced or top-level), and then runs `user-setup` and `adopt` in sequence. The two underlying commands are explicit if you prefer them:
+
+```bash
+metaensemble user-setup --layout=namespaced    # once per machine: vendors runtime to ~/.metaensemble/runtime/, wires commands/hooks/statusline
+# or
+metaensemble user-setup --layout=top-level # same, but slash commands install top-level under ~/.claude/commands/
+
+metaensemble adopt                         # per project: writes <project>/.metaensemble/ and honors install-decisions
+```
+
+`user-setup` is global (one layout for the whole machine; re-run with a different layout to switch). `adopt` is per-project and portable — run it once per project you want to register.
+
+The inspection is the load-bearing piece. It writes two files into `<project>/.metaensemble/`:
+
+- A short Markdown report naming what was found, what we recommend, and why.
+- `install-decisions.yaml`, the editable choice surface. Every agent in your setup and every curated Role MetaEnsemble ships gets one entry with a sensible default. It also records the project's memory surfaces (`CLAUDE.md` and friends) so dispatch contracts hand Executors your existing project memory instead of rebuilding it. Read once, edit only what you disagree with.
+
+Per-agent decisions span four cases (`collision`, `user_unique`, `curated_relevant`, `curated_optional`) and seven actions (`keep_yours`, `take_ours`, `keep_both`, `preserve`, `convert`, `activate`, `retire`). The installer reads the file and honors every choice. Nothing the user authored is silently converted; the default for every collision is to keep the user's agent.
+
+Recovery mirrors the install split. `metaensemble unadopt` reverses one project's adoption: it walks `<project>/.metaensemble/backups/` in reverse, reverses project-scope actions, strips the managed `.gitignore` block, and leaves user-level integration intact. `metaensemble user-teardown` reverses `user-setup` by removing managed `~/.claude/` symlinks and hook entries. Each command accepts `--purge-state` for the matching `.metaensemble/` directory. For a full local rollback after live testing, run `metaensemble reconcile --older-than-minutes 0` first so stranded pending Runs are written to the Ledger, then run `metaensemble unadopt --purge-state` from the project root and `metaensemble user-teardown --purge-state` from anywhere. `metaensemble export-agents` reverse-converts MetaEnsemble Roles back to Claude Code agent files, even when the install's backups directory is missing. Every contract above is tested.
+
+Starter packs (`--pack ml`, `--pack web`, `--pack data`) are planned for a future release.
+
+If your project lives in an iCloud-synced directory (e.g., `~/Desktop/` with iCloud Desktop & Documents Sync enabled), consider excluding `.venv/` from iCloud sync. iCloud's conflict-resolution against rapid `pip install` file churn produces phantom duplicate files in `site-packages`; MetaEnsemble filters them correctly but they consume iCloud quota and slow installs. `metaensemble doctor` C11 surfaces this state as a WARN with remediation. The same caveat applies more strongly to `.metaensemble/state/`: when iCloud places `department.db` into a dataless placeholder state, SQLite's `open()` can fail intermittently and PreToolUse hooks surface as `Agent hook error` with no stderr. The robust fix is to host active MetaEnsemble projects outside iCloud-synced paths, or exclude the project from iCloud Drive. `metaensemble doctor` C4 names this cause when it detects the layout. See [USER-GUIDE.md — When something feels off](./docs/USER-GUIDE.md) for the troubleshooting recipe.
+
+See [DEPLOYMENT.md](./docs/DEPLOYMENT.md) for the per-action behaviour and the full reference. See [ARCHITECTURE.md §4 — Portability](./docs/ARCHITECTURE.md) for the layering, merge order, and the hard rule that keeps Core project-agnostic.
+
+---
+
+## Status
+
+v0.2.0. All core phases complete and tested:
+
+- Typed substrate (Manifest YAML, Brief JSON, Ledger SQLite + JSONL).
+- Lifecycle hooks for SessionStart, PreToolUse, PostToolUse, Write/deliverable-sync, file-tool provenance, SubagentStop (background-dispatch finalization), and Stop, with command-injection invariants enforced by an audit test.
+- Principal-facing surface: seven slash commands plus CLI subcommands including `metaensemble setup`, `metaensemble user-setup`, `metaensemble adopt`, `metaensemble unadopt`, `metaensemble user-teardown`, `metaensemble reconcile`, `metaensemble eval`, `metaensemble stats`, and `metaensemble projects`.
+- Multi-instance patterns (fanout / consensus / shadow / peer-review) with the `N ≥ 2` guard enforced deterministically by the PreToolUse marker hook.
+- Installer with idempotent re-runs, explicit purge modes, and a residue report after every uninstall.
+- Five-axis deliverable check on successful Runs: pytest, bandit, ruff, radon, and coverage for `.py` deliverables, plus project-configured per-axis commands (`axis_commands` in `quality.yaml`) so non-Python deliverables are checked across the same correctness/security/maintainability/complexity/coverage axes; quality runners ship in the `[test]` extras so CI runs the real tools.
+- Failed-run accounting via the `interrupted` and `budget_exceeded` outcomes (schema migration 002) plus the two-layer reconcile module.
+- Ledger field completeness — every documented Ledger field (Role version, model, tool use, files touched, output, gate state, review findings) is a column with an assertion test.
+- Evaluation harness under `evals/` with replay/smoke/full tiers, Wilson confidence intervals, and `pass@budget` / `quality_per_1k_tokens` / `orchestration_overhead_ratio` metrics. The shipped replay pack is a non-empirical bootstrap fixture. Live smoke/full runs are wired for side-effect-free classification-smoke checks; calibration and baseline-superiority claims still require larger labeled/fixture sets.
+
+v0.2.0 is feedback-first. Issues are welcome; see [CONTRIBUTING.md](./CONTRIBUTING.md) to get started.
+
+See [PERFORMANCE.md](./docs/PERFORMANCE.md) for the engineering contract and benchmark numbers, [SYSTEM-CARD.md](./docs/SYSTEM-CARD.md) for known limitations and intended-use boundaries, and [SECURITY.md](./SECURITY.md) for the trust model.
+Release publication is gated by [RELEASE-CHECKLIST.md](./docs/RELEASE-CHECKLIST.md).
+
+---
+
+## Where to start
+
+- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — the layered design, the data model, the lifecycle, what MetaEnsemble is and is not.
+- **[USER-GUIDE.md](./docs/USER-GUIDE.md)** — a friendly Principal guide for day-one users.
+- **[PERFORMANCE.md](./docs/PERFORMANCE.md)** — the binding engineering contract: token budgets, time budgets, query rules, and CI-gated benchmarks. Required reading before changing performance-sensitive code.
+- **[RELEASE-CHECKLIST.md](./docs/RELEASE-CHECKLIST.md)** — artifact, security, installer, and live-eval gates for publishing a release.
+- **[GLOSSARY.md](./docs/GLOSSARY.md)** — every term defined precisely, every analog named.
+
+---
+
+## Operating principles
+
+Three values drive every design choice in MetaEnsemble:
+
+1. **Conserve the budget.** The constraint is window exhaustion, not dollars. Per-Executor model tiering, terse wire format, schema-driven handoffs that eliminate re-search — all designed to fit more useful work in fewer tokens.
+2. **Move fast.** Parallel dispatch is a primitive, not a workaround. Hooks fire on lifecycle events automatically. The Principal never types boilerplate.
+3. **Hold the line on quality.** Speed and budget never come at the cost of standards. The schema layer enforces correctness; the Ledger enforces accountability; the Deliverable channel preserves institutional memory at full fidelity.
+
+If a proposed feature compromises any of these three, it does not ship.

metaensemble-0.2.0/README.md

@@ -0,0 +1,194 @@
+# MetaEnsemble
+
+**Stable identity, typed contracts, and observable runs for ensembles of cognitive agents.**
+
+MetaEnsemble gives every agent a persistent ID, every handoff a schema-validated contract, and every run an entry in an append-only ledger. Multiple agents instantiated from one Role specification execute in parallel. Identities survive across sessions. Token-efficient by construction.
+
+**v0.2.0 status:** feedback-first release. The software records and gates local agent work, but measured quality-per-token improvements remain a product hypothesis until the live evaluation set is larger and fully baseline-comparable. See [SYSTEM-CARD.md](./docs/SYSTEM-CARD.md).
+
+---
+
+## Why MetaEnsemble exists
+
+Coordinating multiple cognitive agents tends to fail in the same three places:
+
+1. **No stable identity.** Each agent invocation is anonymous. No way to say "follow up with the same Executor next week."
+2. **No typed handoffs.** Context passes between agents as free-form prose. Every receiver re-derives state by searching, re-reading, re-grepping.
+3. **No observability.** Token spend, model choice, outcome — nothing captured per run. Optimization is guesswork.
+
+MetaEnsemble fixes all three at the substrate, not as features. Every primitive in the system carries an ID, every transport is schema-validated, every execution lands in the Ledger.
+
+---
+
+## What MetaEnsemble gives you
+
+- **Persistent identities.** Every Executor has a UUIDv7 and a short alias (`arch-7b3`). Resume any past Executor across sessions with `/relaunch arch-7b3`.
+- **Typed contracts.** Handoffs travel as YAML Manifests validated against a JSON Schema. Inter-Executor messages travel as terse JSON Briefs. No prose context-injection, no re-search on the receiving side.
+- **Observable runs.** Append-only Ledger (SQLite live, JSONL mirror for replay) records every Run with token cost, requested model tier, runtime-observed model when available, outcome, and links to its Deliverable.
+- **MetaEnsemble dispatch.** Spawn N Executors from one Role spec for parallel hypothesis exploration, consensus review, or fan-out implementation. Default is N=1; multi-instance is opt-in and currently validated at the planning/protocol layer.
+- **Cross-session continuity.** An Executor's identity is a Ledger row, not a live process. Relaunch is cheap (last Brief + last Deliverable summary) by default, deep (`--full`) when needed.
+- **Two-channel design.** Machine-to-machine traffic (Briefs) stays terse and structured. Human-facing output (Deliverables) stays full English. Same Run produces both. No "compression tier" knob to misset.
+- **Threshold-based cost gating.** The Coordinator auto-decides cheap, reversible work. It surfaces only the calls that warrant Principal judgment, in a structured options table — never as conversational back-and-forth.
+
+---
+
+## Primitives
+
+| Term | Shape | What it is |
+|---|---|---|
+| **Principal** | The human running the system | The person who dispatches work and approves above-threshold decisions. Maps to the IAM Principal concept. |
+| **Coordinator** | The main agent in the active session | Plans Tasks, dispatches Executors, validates contracts, synthesizes Deliverables. Maps to the Kafka / ZooKeeper / Cassandra coordinator pattern. |
+| **Role** | Markdown file with frontmatter spec | The Job Description. Declarative, versioned. Maps to a Kubernetes Deployment spec or IAM Role. |
+| **Executor** | Row in the registry, identified by UUIDv7 + alias | A live instance of a Role. Multiple per Role per Task. Survives sessions. Maps to a Spark Executor or K8s Pod. |
+| **Task** | Unit of work | What the Principal asks the ensemble to do. Has dependencies, expected deliverables, budget. |
+| **Run** | Row in the Ledger | One execution attempt by one Executor for one Task. Maps to an MLflow run. |
+| **Brief** | Schema-validated JSON | Wire-format message between Executors. Terse, machine-targeted. |
+| **Manifest** | Schema-validated YAML | Handoff contract. Typed pointers to files, line ranges, schemas, prior runs. Maps to a dbt or OpenAPI manifest. |
+| **Deliverable** | Markdown report | Human-readable output. English prose. Institutional memory. |
+| **Ledger** | SQLite + JSONL mirror | Append-only log of every Run. Queryable, replayable. Maps to MLflow tracking. |
+| **Registry** | View over the Ledger + Executor table | Current-state snapshot. Live Executors, open Tasks, dependencies. Maps to a service-mesh control-plane view. |
+| **Dispatch** | Verb / slash command | The act of launching N Executors of a Role for a Task. |
+
+---
+
+## High-level flow
+
+```
+                ┌─────────────────────┐
+                │      Principal      │  (you)
+                └──────────┬──────────┘
+                           │ intent
+                ┌──────────▼──────────┐
+                │     Coordinator     │  plans, dispatches, synthesizes
+                └─────┬────────┬──────┘
+                      │        │
+        ┌─────────────┘        └───────────┐
+        │                                  │
+   ┌────▼─────────┐                ┌───────▼──────┐
+   │ Role: backend│                │ Role: review │
+   │  spec file   │                │  spec file   │
+   └────┬─────────┘                └───────┬──────┘
+        │  dispatch N=2                    │  dispatch N=3
+   ┌────┴────┐                       ┌─────┼─────┐
+   ▼         ▼                       ▼     ▼     ▼
+ ┌─────┐  ┌─────┐                  ┌────┐┌────┐┌────┐
+ │be-1 │  │be-2 │                  │rv-1││rv-2││rv-3│
+ └──┬──┘  └──┬──┘                  └─┬──┘└─┬──┘└─┬──┘
+    │ Brief  │ Brief                 │     │     │
+    ▼        ▼                       ▼     ▼     ▼
+ ┌────────────────────────────────────────────────┐
+ │              Ledger (SQLite + JSONL)           │
+ └────────────────────────────────────────────────┘
+                          │
+                          ▼
+                  ┌──────────────┐
+                  │ Deliverables │  English, for humans
+                  └──────────────┘
+```
+
+A single `/dispatch` produces N Executors across one or more Roles. Each Executor emits a Brief downstream and a Deliverable upstream. Every Run is logged. The Principal sees Deliverables and the standup view; never the wire traffic.
+
+---
+
+## Why two channels
+
+A single Run produces two artifacts:
+
+- The **Brief** is what the next Executor receives. Terse JSON. Schema-validated. Machine-targeted. Cheap to emit, cheap to parse.
+- The **Deliverable** is what you, the Principal, read. Full English. Prose. Institutional memory.
+
+These are not intensity tiers. They are different artifacts for different audiences, produced together. The receiving Executor does not parse English; the human does not parse JSON. Each gets the format that earns its place.
+
+---
+
+## How it runs
+
+MetaEnsemble runs entirely on your laptop. Clone the repo, drop the conventions into your local agent runtime configuration, and dispatch. No servers, no cloud accounts, no hosting. Your Ledger, your Executors, your Briefs all live on your filesystem. State is portable: copy the repo and the state directory, and MetaEnsemble runs anywhere the agent runtime is installed.
+
+---
+
+## Adopting MetaEnsemble in your project
+
+MetaEnsemble is project-agnostic by design. Three layers, with project-specific knowledge confined to the project layer:
+
+```
+metaensemble/                           # shipped with MetaEnsemble; project-agnostic
+~/.metaensemble/                # per-engineer preferences; the vendored runtime (runtime/, runtime-versions/); the runner at runtime/bin/me-run
+<your-project>/.metaensemble/   # project-specific state, manifests, and install decisions
+```
+
+The adoption flow has two layers, asked separately:
+
+```bash
+metaensemble setup               # interactive wizard: picks a project, asks for layout, runs the two steps below
+```
+
+The wizard lists every Claude Code project on this machine, lets you pick one, asks once for the layout (namespaced or top-level), and then runs `user-setup` and `adopt` in sequence. The two underlying commands are explicit if you prefer them:
+
+```bash
+metaensemble user-setup --layout=namespaced    # once per machine: vendors runtime to ~/.metaensemble/runtime/, wires commands/hooks/statusline
+# or
+metaensemble user-setup --layout=top-level # same, but slash commands install top-level under ~/.claude/commands/
+
+metaensemble adopt                         # per project: writes <project>/.metaensemble/ and honors install-decisions
+```
+
+`user-setup` is global (one layout for the whole machine; re-run with a different layout to switch). `adopt` is per-project and portable — run it once per project you want to register.
+
+The inspection is the load-bearing piece. It writes two files into `<project>/.metaensemble/`:
+
+- A short Markdown report naming what was found, what we recommend, and why.
+- `install-decisions.yaml`, the editable choice surface. Every agent in your setup and every curated Role MetaEnsemble ships gets one entry with a sensible default. It also records the project's memory surfaces (`CLAUDE.md` and friends) so dispatch contracts hand Executors your existing project memory instead of rebuilding it. Read once, edit only what you disagree with.
+
+Per-agent decisions span four cases (`collision`, `user_unique`, `curated_relevant`, `curated_optional`) and seven actions (`keep_yours`, `take_ours`, `keep_both`, `preserve`, `convert`, `activate`, `retire`). The installer reads the file and honors every choice. Nothing the user authored is silently converted; the default for every collision is to keep the user's agent.
+
+Recovery mirrors the install split. `metaensemble unadopt` reverses one project's adoption: it walks `<project>/.metaensemble/backups/` in reverse, reverses project-scope actions, strips the managed `.gitignore` block, and leaves user-level integration intact. `metaensemble user-teardown` reverses `user-setup` by removing managed `~/.claude/` symlinks and hook entries. Each command accepts `--purge-state` for the matching `.metaensemble/` directory. For a full local rollback after live testing, run `metaensemble reconcile --older-than-minutes 0` first so stranded pending Runs are written to the Ledger, then run `metaensemble unadopt --purge-state` from the project root and `metaensemble user-teardown --purge-state` from anywhere. `metaensemble export-agents` reverse-converts MetaEnsemble Roles back to Claude Code agent files, even when the install's backups directory is missing. Every contract above is tested.
+
+Starter packs (`--pack ml`, `--pack web`, `--pack data`) are planned for a future release.
+
+If your project lives in an iCloud-synced directory (e.g., `~/Desktop/` with iCloud Desktop & Documents Sync enabled), consider excluding `.venv/` from iCloud sync. iCloud's conflict-resolution against rapid `pip install` file churn produces phantom duplicate files in `site-packages`; MetaEnsemble filters them correctly but they consume iCloud quota and slow installs. `metaensemble doctor` C11 surfaces this state as a WARN with remediation. The same caveat applies more strongly to `.metaensemble/state/`: when iCloud places `department.db` into a dataless placeholder state, SQLite's `open()` can fail intermittently and PreToolUse hooks surface as `Agent hook error` with no stderr. The robust fix is to host active MetaEnsemble projects outside iCloud-synced paths, or exclude the project from iCloud Drive. `metaensemble doctor` C4 names this cause when it detects the layout. See [USER-GUIDE.md — When something feels off](./docs/USER-GUIDE.md) for the troubleshooting recipe.
+
+See [DEPLOYMENT.md](./docs/DEPLOYMENT.md) for the per-action behaviour and the full reference. See [ARCHITECTURE.md §4 — Portability](./docs/ARCHITECTURE.md) for the layering, merge order, and the hard rule that keeps Core project-agnostic.
+
+---
+
+## Status
+
+v0.2.0. All core phases complete and tested:
+
+- Typed substrate (Manifest YAML, Brief JSON, Ledger SQLite + JSONL).
+- Lifecycle hooks for SessionStart, PreToolUse, PostToolUse, Write/deliverable-sync, file-tool provenance, SubagentStop (background-dispatch finalization), and Stop, with command-injection invariants enforced by an audit test.
+- Principal-facing surface: seven slash commands plus CLI subcommands including `metaensemble setup`, `metaensemble user-setup`, `metaensemble adopt`, `metaensemble unadopt`, `metaensemble user-teardown`, `metaensemble reconcile`, `metaensemble eval`, `metaensemble stats`, and `metaensemble projects`.
+- Multi-instance patterns (fanout / consensus / shadow / peer-review) with the `N ≥ 2` guard enforced deterministically by the PreToolUse marker hook.
+- Installer with idempotent re-runs, explicit purge modes, and a residue report after every uninstall.
+- Five-axis deliverable check on successful Runs: pytest, bandit, ruff, radon, and coverage for `.py` deliverables, plus project-configured per-axis commands (`axis_commands` in `quality.yaml`) so non-Python deliverables are checked across the same correctness/security/maintainability/complexity/coverage axes; quality runners ship in the `[test]` extras so CI runs the real tools.
+- Failed-run accounting via the `interrupted` and `budget_exceeded` outcomes (schema migration 002) plus the two-layer reconcile module.
+- Ledger field completeness — every documented Ledger field (Role version, model, tool use, files touched, output, gate state, review findings) is a column with an assertion test.
+- Evaluation harness under `evals/` with replay/smoke/full tiers, Wilson confidence intervals, and `pass@budget` / `quality_per_1k_tokens` / `orchestration_overhead_ratio` metrics. The shipped replay pack is a non-empirical bootstrap fixture. Live smoke/full runs are wired for side-effect-free classification-smoke checks; calibration and baseline-superiority claims still require larger labeled/fixture sets.
+
+v0.2.0 is feedback-first. Issues are welcome; see [CONTRIBUTING.md](./CONTRIBUTING.md) to get started.
+
+See [PERFORMANCE.md](./docs/PERFORMANCE.md) for the engineering contract and benchmark numbers, [SYSTEM-CARD.md](./docs/SYSTEM-CARD.md) for known limitations and intended-use boundaries, and [SECURITY.md](./SECURITY.md) for the trust model.
+Release publication is gated by [RELEASE-CHECKLIST.md](./docs/RELEASE-CHECKLIST.md).
+
+---
+
+## Where to start
+
+- **[ARCHITECTURE.md](./docs/ARCHITECTURE.md)** — the layered design, the data model, the lifecycle, what MetaEnsemble is and is not.
+- **[USER-GUIDE.md](./docs/USER-GUIDE.md)** — a friendly Principal guide for day-one users.
+- **[PERFORMANCE.md](./docs/PERFORMANCE.md)** — the binding engineering contract: token budgets, time budgets, query rules, and CI-gated benchmarks. Required reading before changing performance-sensitive code.
+- **[RELEASE-CHECKLIST.md](./docs/RELEASE-CHECKLIST.md)** — artifact, security, installer, and live-eval gates for publishing a release.
+- **[GLOSSARY.md](./docs/GLOSSARY.md)** — every term defined precisely, every analog named.
+
+---
+
+## Operating principles
+
+Three values drive every design choice in MetaEnsemble:
+
+1. **Conserve the budget.** The constraint is window exhaustion, not dollars. Per-Executor model tiering, terse wire format, schema-driven handoffs that eliminate re-search — all designed to fit more useful work in fewer tokens.
+2. **Move fast.** Parallel dispatch is a primitive, not a workaround. Hooks fire on lifecycle events automatically. The Principal never types boilerplate.
+3. **Hold the line on quality.** Speed and budget never come at the cost of standards. The schema layer enforces correctness; the Ledger enforces accountability; the Deliverable channel preserves institutional memory at full fidelity.
+
+If a proposed feature compromises any of these three, it does not ship.

metaensemble-0.2.0/evals/README.md

@@ -0,0 +1,147 @@
+# MetaEnsemble Evaluation Harness
+
+The harness exists so the quality-per-token claim — *the system around
+the model is strong enough to deploy the competence the model already
+has* — can be tested rather than asserted. Replay keeps the harness
+deterministic in CI. Smoke and full tiers make live, side-effect-free
+Claude Code calls and write measured reports under the caller's
+`evals/reports/`.
+The shipped classification data is one narrow smoke fixture, not a calibration set
+and not a statement of product scope. MetaEnsemble is project-agnostic.
+
+## Directory layout
+
+```
+evals/
+├── README.md                  # this file
+├── configs/
+│   └── default.yaml           # eval-cycle parameters (seeds, budget, model routing)
+├── datasets/
+│   ├── suite_a/               # 8 software-engineering tasks
+│   │   ├── README.md
+│   │   └── tasks.yaml
+│   └── suite_b/               # domain-specific classification smoke set
+│       ├── README.md
+│       └── items.yaml
+├── baselines/                 # B1 / B2 / B3 baseline definitions
+│   ├── b1_single_agent.yaml
+│   ├── b2_single_agent_prompted.yaml
+│   ├── b3_subagent_default.yaml
+│   └── b4_best_prompt.yaml    # best-single-agent baseline
+├── cassettes/                 # replay fixtures; bootstrap pack is non-empirical
+├── runners/                   # cell × seed executors
+│   ├── __init__.py
+│   ├── api.py                 # tiered runner: replay / live / smoke
+│   ├── metrics.py             # Wilson CI, pass@budget, quality_per_1k_tokens
+│   └── replay.py              # cassette-based PR runner
+└── reports/                   # generated reports per cycle (gitignored)
+```
+
+## Tiered evaluation
+
+| Tier | When it runs | Live API calls | Budget |
+|---|---|---|---|
+| Replay | Every PR; reads recorded cassette responses. | No. | $0 |
+| Smoke | Nightly cron or local preflight. 1 seed, `MM_full`, classification smoke set only. | Yes. | ~$0.30 default cap |
+| Full | Release-gated. Defaults to 5 seeds × every configured cell. | Yes. | Principal-set cap |
+
+The PR tier exists to keep regressions cheap to catch; the full tier
+exists to certify a release. A release candidate is not allowed
+to claim quality-per-token superiority unless the same report includes
+baseline cells and MetaEnsemble cells over the same task set.
+
+The release ships a compact `evals/cassettes/bootstrap.jsonl` pack so the
+replay tier works in a clean checkout. That pack is deliberately marked
+non-empirical; it verifies the harness mechanics, not MetaEnsemble's
+quality claim. Live smoke/full reports are empirical for the cells and
+datasets actually run; the report notes any skipped deferred fixtures.
+
+## Headline metrics
+
+The harness reports three co-primary metrics per cell:
+
+| Metric | Definition |
+|---|---|
+| `pass@budget` | Pass-rate against the cell's per-task budget. A "win" that overspends does not count. |
+| `quality_per_1k_tokens` | Average score across passing runs divided by tokens / 1000. Directly tests the efficiency thesis. |
+| `orchestration_overhead_ratio` | MetaEnsemble token cost over the best single-agent baseline's token cost, on the same task. |
+
+Plus the supporting metrics in `runners/metrics.py`:
+`failed_run_token_waste`, `time_to_useful_deliverable`,
+`minimum_useful_answer_score`.
+
+For live reports, include these context fields in the release note or
+system-card link: exact model IDs when the runtime exposes them, seed
+count, cells run, skipped fixtures, total observed tokens, estimated vs
+observed token error where available, and any cost-gate or Python
+deliverable-check interventions.
+
+## Suite A — software engineering (8 tasks)
+
+Eight tasks drawn from the project's own backlog and from small
+open-source repos. Each task has:
+
+- A one-paragraph description (English).
+- A frozen-commit starting state (commit SHA of the project under test).
+- Graded acceptance criteria (build passes, tests count ≥ N, lint
+  clean, manifest existed, deliverable file present).
+
+See `evals/datasets/suite_a/tasks.yaml` for the current set.
+
+The current Suite-A rows still contain deferred fixture SHAs. The live
+full tier names those skipped tasks in the report rather than treating
+them as passed or failed. Release certification across software tasks
+requires replacing the deferred SHAs with real fixture repositories.
+
+## Suite B — domain-specific classification (12 items, *smoke only*)
+
+Twelve items is too few for calibration claims. The 12-item set in
+`evals/datasets/suite_b/items.yaml` is the **smoke suite** that proves
+the pipeline end-to-end. It is intentionally narrow; it does not make
+MetaEnsemble domain-specific. Any release claim about a particular domain
+needs its own independently labeled calibration set. The system card states
+this limitation explicitly so no calibration claim is implied by the smoke
+set.
+
+## Running the harness
+
+```bash
+# PR-tier replay (no API calls).
+metaensemble eval --tier replay --cells all
+
+# Nightly smoke (one cell × one seed × classification smoke set only).
+metaensemble eval --tier smoke
+
+# Constrained full-tier check.
+metaensemble eval --tier full --allow-live --cells MM_full --seeds 1 --budget-usd 0.30
+
+# Release-gated full cycle once fixture SHAs and budget are set.
+metaensemble eval --tier full --allow-live --cells all --seeds 5 --budget-usd 0.30
+```
+
+The output report lands in the current working directory at
+`evals/reports/<UTC-date>-<tier>.md` and is linked from
+`PERFORMANCE.md §4` once a cycle ships.
+
+Supported flags:
+
+| Flag | Meaning |
+|---|---|
+| `--cells all` or `--cells A,B` | Select all cells or a comma-separated subset. Smoke defaults to `MM_full`; replay/full default to all. |
+| `--seeds N` | Override seed count. Smoke defaults to 1; replay/full default to `evals/configs/default.yaml`. |
+| `--budget-usd X` | Override the live-tier per-run budget shown in preflight. |
+| `--allow-live` | Required before the full tier proceeds past preflight. |
+
+## Sign-off thresholds (D-8, D-9)
+
+D-8 and D-9 are numerical full-tier release gates:
+
+- **D-8 orchestration overhead**: any measured MetaEnsemble cell above
+  `2.0x` the best single-agent prompt baseline (`B4`) blocks the full
+  tier's ship verdict.
+- **D-9 failed-run waste**: failed and budget-exceeded runs above `10%`
+  of total evaluated tokens block the full tier's ship verdict.
+
+The thresholds live in `evals/configs/default.yaml`. If a full run does
+not include the `B4_best_prompt` baseline, D-8 is reported as not
+evaluated rather than silently passing.

metaensemble-0.2.0/evals/cassettes/README.md

@@ -0,0 +1,10 @@
+# Eval Cassettes
+
+`bootstrap.jsonl` is a v0.1.0 replay fixture pack. It exists so the
+zero-cost replay tier exercises task loading, cell selection, metrics,
+and report rendering in a clean checkout.
+
+It is not empirical benchmark evidence. Each record is marked
+`source: bootstrap_fixture_not_empirical`; the first live smoke/full
+cycle should replace or supplement this pack with recorded cassette
+outputs from real runs.