# world-model-optimizer - Doramagic AI Context Pack

> Positioning: a pre-install experience and judgment asset. It helps the host AI get off to a good start, but it does not mean the project has already been installed, run, or validated.

## Sufficiency Principle

- **Sufficiency over compression**: The AI Context Pack should be sufficient for the host AI to understand the project's value, capability boundaries, entrypoints, risks, and evidence sources before starting work; it may be layered, but it does not aim for the shortest possible summary.
- **Compression policy**: Compress only noise and duplication, never context that affects judgment or the quality of the work.

## How the Host AI Should Use This

You are reading the AI Context Pack that Doramagic compiled for world-model-optimizer. Treat it as pre-work context: help the user understand who it fits, what it can do, how to start, what must be verified after install, and where the risks are. Do not claim that you have already installed, run, or executed the target project.

## Claim Consumption Rules

- **Fact source**: Repo Evidence + Claim/Evidence Graph; the Human Wiki only supplies salience, terminology, and narrative structure.
- **Minimum status for a fact**: `supported`
- `supported`: May be used as a project fact, but the answer must cite the claim_id and evidence path.
- `weak`: Usable only as a low-confidence lead; the user must be asked to keep verifying.
- `inferred`: Usable only for risk notes or open questions; must not be packaged as a project fact.
- `unverified`: Must not be used as fact; state clearly that evidence is insufficient.
- `contradicted`: Must show the conflicting sources and must not force a single version on the user's behalf.

## Who It Fits Best

- **Users who want to bring professional workflows into a host AI**: The repo contains Skill documents. Evidence: `.claude/skills/improve-judge/SKILL.md`, `.claude/skills/ready-for-merge/SKILL.md` Claim: `clm_0003` supported 0.86

## What It Can Do

- **AI Skill / Agent Instruction Asset Library** (Previewable before install): The project contains Skill or Agent instruction files that a host AI can read, useful for bringing professional workflows into hosts like Claude, Codex, or Cursor. Evidence: `.claude/skills/improve-judge/SKILL.md`, `.claude/skills/ready-for-merge/SKILL.md` Claim: `clm_0001` supported 0.86
- **Command-Line Startup or Install Flow** (Verify after install): The project documentation contains runnable commands; real use requires running them in a local or host environment. Evidence: `README.md`, `packages/environment-capture/README.md`, `packages/environment-capture/bird-sql/README.md`, `packages/environment-capture/swe-bench/README.md` et al. Claim: `clm_0002` supported 0.86

## How to Start

- `pip install world-model-optimizer` Evidence: `README.md` Claim: `clm_0004` supported 0.86, `clm_0005` supported 0.86
- `pip install "world-model-optimizer[e2b]"` Evidence: `README.md` Claim: `clm_0005` supported 0.86
- `pip install gdown` Evidence: `packages/environment-capture/bird-sql/README.md` Claim: `clm_0006` supported 0.86
- `git clone --depth 1 https://github.com/SWE-agent/mini-swe-agent.git` Evidence: `packages/environment-capture/swe-bench/README.md` Claim: `clm_0007` supported 0.86
- `git clone --depth 1 https://github.com/sierra-research/tau2-bench.git` Evidence: `packages/environment-capture/tau-bench/README.md` Claim: `clm_0008` supported 0.86
- `pip install environment-capture            # the library: contract, capture driver, hygiene, hub fetch` Evidence: `packages/environment-capture/README.md` Claim: `clm_0009` supported 0.86
- `pip install 'environment-capture[fetch]'   # + huggingface_hub, for publishing bundles` Evidence: `packages/environment-capture/README.md` Claim: `clm_0010` supported 0.86
- `curl -LO https://huggingface.co/datasets/experiential-labs/wmo-dabstep-traces/resolve/main/traces.otel.jsonl` Evidence: `packages/environment-capture/README.md` Claim: `clm_0011` supported 0.86
- `pip install "llm-waterfall[bedrock]"           # extras: bedrock, openai, anthropic, azure, all` Evidence: `packages/llm-waterfall/README.md` Claim: `clm_0012` supported 0.86
- `pip install "llm-waterfall[all]"` Evidence: `packages/llm-waterfall/README.md` Claim: `clm_0013` supported 0.86

## Continue-or-Stop Decision Card

- **Current recommendation**: Needs admin / security approval
- **Why**: Continuing may involve secrets, accounts, external services, or sensitive context; get admin or security approval first.

### 30-Second Read

- **What to do now**: Needs admin / security approval
- **Minimum safe next step**: Run Prompt Preview first; if credentials or an enterprise environment are involved, get approval before trialing
- **Do not trust yet**: Real output quality cannot be trusted before install.
- **Continuing will touch**: Command execution, Host AI configuration, Local environment or project files

### What You Can Trust Now

- **Target-audience signal: Users who want to bring professional workflows into a host AI** (supported): Backed by a supported claim or project evidence, but that still is not the same as real install results. Evidence: `.claude/skills/improve-judge/SKILL.md`, `.claude/skills/ready-for-merge/SKILL.md` Claim: `clm_0003` supported 0.86
- **Capability exists: AI Skill / Agent Instruction Asset Library** (supported): You can trust that the project contains signals of this capability; whether it fits your specific task still needs trial or after-install verification. Evidence: `.claude/skills/improve-judge/SKILL.md`, `.claude/skills/ready-for-merge/SKILL.md` Claim: `clm_0001` supported 0.86
- **Capability exists: Command-Line Startup or Install Flow** (supported): You can trust that the project contains signals of this capability; whether it fits your specific task still needs trial or after-install verification. Evidence: `README.md`, `packages/environment-capture/README.md`, `packages/environment-capture/bird-sql/README.md`, `packages/environment-capture/swe-bench/README.md` et al. Claim: `clm_0002` supported 0.86
- **There are Quick Start / install-command signals** (supported): You can trust that the docs mention a startup or install entrypoint; do not run it directly in your primary environment because of that. Evidence: `README.md` Claim: `clm_0004` supported 0.86, `clm_0005` supported 0.86

### What You Cannot Trust Yet

- **Real output quality cannot be trusted before install.** (unverified): Prompt Preview can only show how it guides you; it cannot prove result quality in the real project.
- **Host AI version compatibility cannot be trusted before install.** (unverified): Host loading rules and version differences across Claude, Cursor, Codex, Gemini, and others must be verified in a real environment.
- **That it will not pollute your existing host AI's behavior cannot be trusted directly.** (inferred): Skill, plugin, and AGENTS/CLAUDE/GEMINI instructions may change the host AI's default behavior. Evidence: `.claude/skills/improve-judge/SKILL.md`, `.claude/skills/ready-for-merge/SKILL.md`, `AGENTS.md`, `CLAUDE.md`
- **Safe rollback cannot be assumed by default.** (unverified): Unless the project clearly provides uninstall and recovery instructions, verify in an isolated environment first.
- **After a real install, is it compatible with the user's current host AI version?** (unverified): Compatibility can only be verified in the actual host environment.
- **Does the project's output quality meet the user's specific task?** (unverified): The pre-install preview can only show flow and boundaries; it cannot replace real evaluation.
- **Do the install commands require network access, permissions, or global writes?** (unverified): This affects install risk in both enterprise and personal environments. Evidence: `README.md`

### What Continuing Will Touch

- **Command execution**: Package managers, network downloads, the local plugin directory, project config, or the user's home directory. Why: Running the very first command can already change your environment; decide whether it is worth running first. Evidence: `README.md`, `packages/environment-capture/README.md`, `packages/environment-capture/bird-sql/README.md`, `packages/environment-capture/swe-bench/README.md` et al.
- **Host AI configuration**: The plugin, Skill, or rule-loading config of hosts like Claude/Codex/Cursor/Gemini/OpenCode. Why: Host configuration changes how the AI works afterward and may conflict with the user's existing rules. Evidence: `.claude/skills/improve-judge/SKILL.md`, `.claude/skills/ready-for-merge/SKILL.md`, `AGENTS.md`, `CLAUDE.md`
- **Local environment or project files**: Install results, plugin caches, project config, or local dependency directories. Why: The write scope and rollback path cannot be proven before install and need isolated verification. Evidence: `README.md`, `packages/environment-capture/README.md`, `packages/environment-capture/bird-sql/README.md`, `packages/environment-capture/swe-bench/README.md` et al.
- **Environment variables / API keys**: Project entry docs explicitly showing API key, token, secret, or account credential configuration. Why: If a real install needs credentials, use test credentials first and go through a permission/compliance review. Evidence: `.agents/docs/reference/rag-scaling-methodology.md`, `README.md`, `docs/reference/distill.md`, `docs/reference/failover.md` et al.
- **Host AI context**: The AI Context Pack, Prompt Preview, Skill routing, risk rules, and project facts. Why: Importing context affects the host AI's later judgment, so avoid packaging unverified items as facts.

### Minimum Safe Next Steps

- **Run Prompt Preview first**: Use a pre-install interactive trial to judge whether the way of working fits; it needs no authorization or environment change. (applies when: Applies to any project, especially when output quality is unknown.)
- **Trial-install only in an isolated directory or a test account**: Avoid letting install commands pollute your primary host AI, real projects, or home directory. (applies when: When there are signals of command execution, plugin config, or local writes.)
- **Back up your host AI configuration first**: Skill, plugin, and rule files may change the default behavior of Claude/Cursor/Codex. (applies when: When there is a plugin manifest, a Skill, or a host rule entrypoint.)
- **Do not use real production credentials**: Once an environment variable / API key enters the host or toolchain, it can create account and compliance risk. (applies when: When environment signals like API, TOKEN, KEY, or SECRET appear.)
- **After install, verify just one minimal task**: Verify loading, compatibility, output quality, and rollback first, then decide whether to use it deeply. (applies when: When moving from a trial into a real workflow.)

### Exit Plan

- **Preserve the pre-install state**: Record the original host config and project state so you can later judge whether it is recoverable.
- **Be ready to remove the host plugin / Skill / rule entrypoint**: If behavior is off after the trial install, you can restore the host AI to its pre-trial state.
- **Record the install commands and written paths**: Without clear uninstall instructions, you at least need to know which directories or configs to clean up manually.
- **Be ready to revoke test API keys or tokens**: If test credentials leak or are misused, you can cut losses quickly.
- **If there is no rollback path, do not enter your primary environment**: No rollback is a blocker before continuing; do not proceed on trust or luck.

## What Can Only Be Previewed

- Explain who the project fits and what it can do
- Demonstrate a typical conversation flow based on project docs
- Help the user decide whether it is worth installing or researching further

## What Must Be Verified After Install

- Actually installing the Skill, plugin, or CLI
- Running scripts, modifying local files, or accessing external services
- Verifying real output quality, performance, and compatibility

## Boundary & Risk Decision Card

- **Mistaking the pre-install preview for a real run**: The user may overestimate how much configuration, permission, and compatibility verification the project has already done. Mitigation: Clearly separate prompt_preview_can_do from runtime_required. Claim: `clm_0014` inferred 0.45
- **Command execution will modify the local environment**: Install commands may write to the user's home directory, the host plugin directory, or project configuration. Mitigation: Run in an isolated environment or a test account first. Evidence: `README.md`, `packages/environment-capture/README.md`, `packages/environment-capture/bird-sql/README.md`, `packages/environment-capture/swe-bench/README.md` et al. Claim: `clm_0015` supported 0.86
- **To confirm**: After a real install, is it compatible with the user's current host AI version?. Why: Compatibility can only be verified in the actual host environment.
- **To confirm**: Does the project's output quality meet the user's specific task?. Why: The pre-install preview can only show flow and boundaries; it cannot replace real evaluation.
- **To confirm**: Do the install commands require network access, permissions, or global writes?. Why: This affects install risk in both enterprise and personal environments.

## Pre-Work Working Context

### Loading Order

- First read how_to_use.host_ai_instruction to establish the boundaries of this pre-install judgment asset.
- Read claim_graph_summary to confirm facts come from the Claim/Evidence Graph, not the Human Wiki narrative.
- Then read intended_users, capabilities, and quick_start_candidates to judge whether the user is a match.
- When you need to carry out a concrete task, check role_skill_index first, then evidence_index.
- For real install, file modification, network access, performance, or compatibility questions, turn to risk_card and boundaries.runtime_required.

### Task Routes

- **AI Skill / Agent Instruction Asset Library**: Use role_skill_index / evidence_index to help the user pick a usable role, Skill, or workflow first. Boundary: Can be experienced via a pre-install Prompt. Evidence: `.claude/skills/improve-judge/SKILL.md`, `.claude/skills/ready-for-merge/SKILL.md` Claim: `clm_0001` supported 0.86
- **Command-Line Startup or Install Flow**: State that this is an after-install capability first, then give a pre-install checklist. Boundary: Must be verified after a real install or run. Evidence: `README.md`, `packages/environment-capture/README.md`, `packages/environment-capture/bird-sql/README.md`, `packages/environment-capture/swe-bench/README.md` et al. Claim: `clm_0002` supported 0.86

### Context Scale

- Total files: 1064
- Important-file coverage: 40/1064
- Evidence index entries: 80
- Role / Skill entries: 2

### Handling Insufficient Evidence

- **missing_evidence**: State that evidence is insufficient and ask the user for the target file, a README section, or after-install verification records; do not fill in facts.
- **out_of_scope_request**: State that the task is beyond the current AI Context Pack's evidence scope and suggest the user check the Human Manual or verify after a real install.
- **runtime_request**: Provide a pre-install checklist and command sources, but do not run commands for the user or claim they have been run.
- **source_conflict**: Show the conflicting sources side by side, mark them as unverified, and do not force a single version.

## Prompt Recipes

### Fit assessment

- Goal: Judge whether this project fits the user's current task.
- Expected output: A fit conclusion, key reasons, evidence citations, what can be previewed before install, what must be verified after install, and a next-step recommendation.

```text
Based on the AI Context Pack for world-model-optimizer, ask me 3 necessary questions first, then judge whether it fits my task. The answer must cover: who it fits, what it can do, what it cannot do, whether it is worth installing, and where the evidence comes from. Every project fact must cite evidence_refs, source_paths, or a claim_id.
```

### Pre-install experience

- Goal: Let the user feel the core workflow before installing, while avoiding packaging the preview as real capability or a marketing promise.
- Expected output: An experience script with boundary labels, an after-install verification checklist, and a cautious recommendation; with no real-run promises or strong marketing language.

```text
Treat world-model-optimizer as a pre-install experience asset, not an already-installed tool or a real runtime environment.

Output exactly four parts:
1. Ask me 3 necessary questions first.
2. Give an "experience script": use the three labels [Previewable before install], [Must verify after install], and [Insufficient evidence] to show how it might guide the workflow.
3. Give an after-install verification checklist: list which capabilities can only be confirmed after a real install, real host loading, and a real project run.
4. Give a cautious recommendation: only "worth researching/trialing further", "add information before deciding", or "not recommended to continue"; do not endorse the project.

Hard boundaries:
- Do not claim you have installed, run, executed tests, modified files, or produced real results.
- Do not write promise-like phrasing such as "auto-adapts", "guarantees passing", "perfect fit", or "strongly recommend installing".
- If you describe how it works after install, you must use a conditional such as "if installed successfully and the host loads the Skill correctly, it might...".
- The experience script may only be written as "example lines / hypothetical flow": use "might ask / might suggest / might show", not "has written, has generated, has passed, is running, is generating".
- Prompt Preview does not hand out install commands; if the user is ready to trial, only prompt them to read Quick Start and the Risk Card first and to verify in an isolated environment.
- Every project fact must come from a supported claim, evidence_refs, or source_paths; inferred/unverified items can only be risks or open questions.

```

### Role / Skill selection

- Goal: Pick the best-matching asset from the project's roles or Skills.
- Expected output: A list of candidate roles or Skills, each with an applicable scenario, evidence paths, risk boundary, and whether after-install verification is needed.

```text
Read role_skill_index and recommend 3-5 of the most relevant roles or Skills for my target task. For each recommendation, state the applicable scenario, likely output, risk boundary, and evidence_refs.
```

### Risk pre-check

- Goal: Identify environment, permission, rule-conflict, and quality risks before installing or adopting.
- Expected output: A checklist of environment, permission, dependency, license, host-conflict, quality risk, and unknown items.

```text
Based on risk_card, boundaries, and quick_start_candidates, give me a pre-install risk pre-check list. Do not run commands for me; only explain what I should check, why, and what impact a failure would have.
```

### Host AI kickoff instruction

- Goal: Turn the project context into a host AI instruction for the start of a conversation.
- Expected output: A pre-work instruction with clear boundaries and clear evidence citations, suitable to copy to a host AI.

```text
Based on the AI Context Pack for world-model-optimizer, generate a pre-work instruction I can paste to my host AI. This instruction must obey not_runtime=true and must not claim the project has been installed, run, or produced real results.
```

## Role / Skill Index

- Indexed 2 role / Skill / project-doc entries.

- **improve-judge** (skill): Iteratively improve the RubricJudge or any LLM scorer against a hand-labeled dataset - run the judge, identify false positives/negatives, diagnose why each failed, propose one experiment prompt, model, or context per failure class, and prove the fix without regressing controls. Use when the user distrusts judge scores, asks to improve/calibrate/tune the judge, or a new corpus type needs judge coverage. Activation hint: When the user's task is highly relevant to the workflow described by “improve-judge”, use it for a pre-install experience first, then decide whether to install. Evidence: `.claude/skills/improve-judge/SKILL.md`
- **ready-for-merge** (skill): Mandatory pre-merge gate for every PR. Runs /code-review --fix at an effort level scaled to the PR's breadth, resolves every review comment Cursor, Greptile, humans , and verifies the diff complies with AGENTS.md. Use whenever the user says a PR is ready to merge, asks to merge, or invokes /ready-for-merge. Activation hint: When the user's task is highly relevant to the workflow described by “ready-for-merge”, use it for a pre-install experience first, then decide whether to install. Evidence: `.claude/skills/ready-for-merge/SKILL.md`

## Evidence Index

- Indexed 80 evidence entries.

- **docs — finished products only, kept deliberately small** (documentation): docs — finished products only, kept deliberately small Evidence: `docs/README.md`
- **.agents/docs — working docs** (documentation): The unclean side of the documentation AGENTS.md rule 5 : drafts, design notes, experiment logs, raw results, proposals. Committed so it transfers across worktrees and chats; pruned periodically; nothing outside .agents/ may depend on it. When something matures, its cleaned product is promoted to docs/ writeups → docs/research/ , verified how-tos → docs/reference/ and the working copy dies here. The Notion Eng Docs database was migrated here 2026-07-02; files keep their Notion area / status in frontmatter. Evidence: `.agents/docs/README.md`
- **benchmark-grid — reference run inputs & artifacts** (documentation): benchmark-grid — reference run inputs & artifacts Evidence: `.agents/docs/research/benchmark-grid/README.md`
- **.agents — the agents' workspace** (documentation): The unclean side of the work: one-off scripts, experiment runners, plans, scratchpads, drafts. Committed so it transfers across worktrees and chats — but that is the only guarantee. Evidence: `.agents/README.md`
- **World Model Optimizer** (documentation): wmo turns agent traces you already collect into continuous improvement. Start with a model endpoint at frontier quality with 40%+ lower cost. Keep improving it with world model simulations, meta-harness optimization, and model distillation. Evidence: `README.md`
- **web/ - the world-model-optimizer site** (documentation): web/ - the world-model-optimizer site Evidence: `web/README.md`
- **environment-capture** (documentation): Run agent benchmarks for real and record every agent-environment transition — each action → observation pair, exactly as the environment returned it — as OpenTelemetry GenAI JSONL. Integrating a benchmark is one small adapter; ten are already in 5,900+ real trajectories / 27,000+ real transitions captured and published as license-tagged datasets on the Hugging Face Hub https://huggingface.co/experiential-labs . Evidence: `packages/environment-capture/README.md`
- **appworld** (documentation): A stateful multi-app world. AppWorld drops an agent into a simulated world of nine apps Amazon, Gmail, Venmo, Spotify, phone, file system, Splitwise, Todoist, SimpleNote plus a supervisor app for the account, behind 450+ real Python APIs. A task is a natural-language request — e.g. "what is the title of the most-liked song in my Spotify playlists" — and the agent completes it by writing Python that calls apis. . ... against a live, mutable world , signalling completion with apis.supervisor.complete task ... . This is the first adapter whose world state carries across steps variables and world mutations persist , which is exactly the world-model dynamics this benchmark exists to exercise — s… Evidence: `packages/environment-capture/appworld/README.md`
- **bird-sql** (documentation): Text-to-SQL over real SQLite databases. The environment is a workspace holding a fresh COPY of the task's database as database.db plus its DDL as schema.sql ; the agent explores with the sqlite3 CLI and submits a single SQLite SELECT / WITH query as its answer. Scoring is deterministic EXECUTION MATCH — the predicted and gold SQL are each run against a pristine read-only copy of the database and their result rows compared as an order-insensitive multiset order-sensitive when the question implies ordering — see environment capture/benchmarks/bird sql.py . Evidence: `packages/environment-capture/bird-sql/README.md`
- **continual-learning** (documentation): Database-exploration QA over a large, deliberately obfuscated SQLite database. The environment is a workspace holding one shared products.db ~400 MB of Amazon product/review data with cryptic table/column names, prices in integer cents, timestamps in epoch milliseconds, and drifted/corrupt values ; the agent explores it with real sqlite3 / python3 shell commands and submits a final answer. Scoring is deterministic and LLM-free — numeric match within the gold's absolute tolerance, else normalized text exact-match or containment — see environment capture/benchmarks/continual learning.py . Evidence: `packages/environment-capture/continual-learning/README.md`
- **crmarena** (documentation): Professional CRM work over a realistic Salesforce org. Each task is an analyst question — case routing, handle-time and transfer analytics, top-issue identification, entity disambiguation, policy-violation checks, or knowledge QA — answered by querying a real Salesforce-org database accounts, cases, orders, knowledge articles, case history, ... . The environment stages a fresh read-only copy of the org as crm.db plus a generated schema.md and a small query.py runner into the workspace; the agent explores with python3 query.py "SELECT ..." real rows as JSON and submits the value the question asks for. Scoring is deterministic and LLM-free — exact/contains for the analytical tasks Salesforce… Evidence: `packages/environment-capture/crmarena/README.md`
- **dabstep** (documentation): Data-analysis QA over a shared payments dataset and a business-rules manual. Each task is a question whose correct answer requires reading manual.md it defines what "authorized", "fee", and "fraud rate" mean — the raw columns are ambiguous on their own and computing over the CSV/JSON context files with real shell + pandas. The environment stages the task's context files into a fresh workspace's ./data/ directory; the agent explores, analyzes, and submits an answer. Scoring is deterministic numeric tolerance 0.01, normalized string/list match, accepted alternates — see environment capture/benchmarks/dabstep.py . Evidence: `packages/environment-capture/dabstep/README.md`
- **financebench** (documentation): Financial-document QA over real SEC-filing evidence excerpts. The environment is a workspace whose docs/ holds the task's true evidence doc s plus 4 distractors; the agent retrieves with real shell commands and submits an answer. Scoring is deterministic numeric match, token-F1 fallback — see environment capture/benchmarks/financebench.py . Evidence: `packages/environment-capture/financebench/README.md`
- **gaia2** (documentation): A stateful multi-app simulated world. GAIA2 / Meta Agents Research Environments ARE drops an agent into a simulated universe of apps Contacts, Email, Messaging, Calendar, RentAFlat, Shopping, CabApp, CityApp, a sandbox file system, ... pre-populated with fictional user data. A USER message states a task — e.g. "save every apartment in zip codes whose violent-crime rate is 5-10" or "add together the ages of all my contacts in Dublin, then in Galway, and give the absolute difference" — and the agent completes it by calling the apps' real Python tools against a live, mutable world state persists across steps , then answering via AgentUserInterface send message to user . State carries across st… Evidence: `packages/environment-capture/gaia2/README.md`
- **kimi-gui-control** (documentation): Computer-use agent runs that drive macOS GUI apps Safari, Chrome, Notes, Finder, Calculator, … through the macOS Accessibility API plus a shell. Each trajectory is a task like "browse the latest cs.CL listings on arXiv, open the top paper, and report the title, author count, and abstract" : the agent reads the accessibility tree, takes a single targeted action, and re-reads the tree to confirm. Evidence: `packages/environment-capture/kimi-gui-control/README.md`
- **SWE-bench trace capture isolated** (documentation): This directory is a self-contained, local-only capture tool . It runs the real SWE-bench Verified https://www.swebench.com/ benchmark with the standard mini-swe-agent https://github.com/SWE-agent/mini-swe-agent harness and converts the recorded agent trajectories into the world-model-optimizer trace corpus packages/environment-capture/swe-bench/traces.otel.jsonl . Evidence: `packages/environment-capture/swe-bench/README.md`
- **tau2-bench trace capture isolated** (documentation): This directory is a self-contained, local-only capture tool . It runs the real tau²-bench https://github.com/sierra-research/tau2-bench benchmark and converts its trajectories into the world-model-optimizer trace corpus packages/environment-capture/tau-bench/traces.otel.jsonl . Evidence: `packages/environment-capture/tau-bench/README.md`
- **RL smoke harness tau-bench** (documentation): smoke.py exercises every wmo-side data path each downstream training chat will consume end-to-end against the real tau-bench world model on Bedrock, at tiny scale ~30 haiku calls, max steps=3 , 2 scenarios . It exists so we find interface problems in the RL seam here before the transfer prompts spawn four training chats that would each hit the same wall. Evidence: `packages/environment-capture/tau-bench/rl/README.md`
- **terminal-tasks trace capture isolated** (documentation): terminal-tasks trace capture isolated Evidence: `packages/environment-capture/terminal-tasks/README.md`
- **llm-waterfall** (documentation): Pool every LLM quota you own behind one client. Rate limits are issued per model, per provider, per account — but a workload pinned to one backend can only ever use one of them, and stalls the moment it throttles. llm-waterfall chains your backends into a single stateless client: each call walks the chain in order, capacity errors throttling, 5xx, timeouts spill to the next backend, and real errors bad request, auth, validation raise immediately. A six-rung chain sustains roughly the sum of six rate limits instead of the minimum of one — capacity you already pay for, actually reachable. Evidence: `packages/llm-waterfall/README.md`
- **wmo.distill** (documentation): Distill a smaller student from a larger teacher on real agent tasks, training a Tinker LoRA and gating whether the adapter is promoted. Three modes, in descending order of maturity. Evidence: `wmo/distill/README.md`
- **@earendil-works/pi-agent-core** (documentation): Stateful agent with tool execution and event streaming. Built on @earendil-works/pi-ai . Evidence: `wmo/harness/vendor/pi-agent/README.md`
- **Agent guide — world-model-optimizer** (documentation): Agent guide — world-model-optimizer Evidence: `AGENTS.md`
- **Claude** (documentation): See AGENTS.md ./AGENTS.md for project conventions and rules. They apply here in full. Evidence: `CLAUDE.md`
- **This is NOT the Next.js you know** (documentation): This version has breaking changes - APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node modules/next/dist/docs/ before writing any code. Heed deprecation notices. Evidence: `web/AGENTS.md`
- **Claude** (documentation): @AGENTS.md Evidence: `web/CLAUDE.md`
- **Agent guide — llm-waterfall** (documentation): A stateless, provider-agnostic LLM client that sends each call down an ordered waterfall of backends, failing over only on capacity errors throttling / 5xx / timeouts and propagating real client errors immediately. Every call returns which backend served it, token usage, and USD cost. Evidence: `packages/llm-waterfall/AGENTS.md`
- **Package** (package_manifest): { "name": "web", "version": "0.1.0", "private": true, "scripts": { "dev": "next dev", "build": "next build", "start": "next start", "lint": "eslint .", "typecheck": "tsc --noEmit", "index": "node scripts/build-index.mjs" }, "dependencies": { "next": "16.2.10", "react": "19.2.4", "react-dom": "19.2.4" }, "devDependencies": { "@tailwindcss/postcss": "^4", "@types/node": "^20", "@types/react": "^19", "@types/react-dom": "^19", "eslint": "^9", "eslint-config-next": "16.2.10", "tailwindcss": "^4", "typescript": "^5" } } Evidence: `web/package.json`
- **Package** (package_manifest): { "name": "@earendil-works/pi-agent-core", "version": "0.80.3", "description": "General-purpose agent with transport abstraction, state management, and attachment support", "type": "module", "main": "./dist/index.js", "types": "./dist/index.d.ts", "exports": { ".": { "types": "./dist/index.d.ts", "import": "./dist/index.js" }, "./node": { "types": "./dist/node.d.ts", "import": "./dist/node.js" }, "./package.json": "./package.json" }, "files": "dist", "README.md" , "scripts": { "clean": "shx rm -rf dist", "build": "tsgo -p tsconfig.build.json", "test": "vitest --run", "test:harness": "vitest --run --config vitest.harness.config.ts", "coverage:harness": "vitest --run --config vitest.harness.c… Evidence: `wmo/harness/vendor/pi-agent/package.json`
- **Improve the Judge** (skill_instruction): An iterative calibration loop against a hand-labeled dataset. Never tweak the judge from intuition: every change starts from a disagreement you can point at and ends with a case that would catch its regression. Deep background and worked example, if it still exists .agents/ is prunable : .agents/docs/reference/judge-meta-eval-playbook.md . Evidence: `.claude/skills/improve-judge/SKILL.md`
- **Ready for Merge** (skill_instruction): This is the mandatory gate before merging any PR in this repository. Do not tell the user a PR is ready to merge until every step below has been completed and passes. Evidence: `.claude/skills/ready-for-merge/SKILL.md`
- **License** (source_file): 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: Evidence: `packages/environment-capture/LICENSE`
- **License** (source_file): 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: Evidence: `packages/llm-waterfall/LICENSE`
- **License** (source_file): 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: Evidence: `wmo/harness/vendor/pi-agent/LICENSE`
- **Design note: RAG-aware GEPA why, and how leakage is avoided** (documentation): Design note: RAG-aware GEPA why, and how leakage is avoided Evidence: `.agents/docs/design-decisions/rag-aware-gepa.md`
- **Transfer prompt — WM scenario-mining → filtered-BC ablation assume no prior context** (documentation): Transfer prompt — WM scenario-mining → filtered-BC ablation assume no prior context Evidence: `.agents/docs/proposals/HANDOFF.md`
- **Closed-loop evaluation future direction** (documentation): Closed-loop evaluation future direction Evidence: `.agents/docs/proposals/closed-loop-eval-spec.md`
- **Charter: inverse distillation — train an agent from mined scenarios + the world model** (documentation): Charter: inverse distillation — train an agent from mined scenarios + the world model Evidence: `.agents/docs/proposals/inverse-distillation-charter.md`
- **Research directions not yet run** (documentation): A backlog of optimization experiments for the GEPA research harness see GEPA optimization research . Each is "one new Ablation class" away — the framework run ablation , seed aggregation, RubricJudge scoring is already in place. Adding one means writing a conditions list and a run condition, seed that wires the knob, then a scripts/ runner mirroring scripts/run trace scaling.py . Evidence: `.agents/docs/proposals/research-directions.md`
- **Routing optimizer v1: benchmark + implementation proposal DISCUSSION DRAFT** (documentation): Routing optimizer v1: benchmark + implementation proposal DISCUSSION DRAFT Evidence: `.agents/docs/proposals/routing-optimizer-v1.md`
- **Sim–real policy-rank agreement research direction** (documentation): Sim–real policy-rank agreement research direction Evidence: `.agents/docs/proposals/sim-real-policy-rank-agreement.md`
- **Architecture** (documentation): World Model Optimizer turns a frontier LLM into the environment your agent steps against, reconstructed from your own OpenTelemetry traces. This doc is the map: how the packages fit, the data that flows between them, and where to plug in new pieces. Evidence: `.agents/docs/reference/architecture.md`
- **Benchmarks → traces: the real trace source** (documentation): Benchmarks → traces: the real trace source Evidence: `.agents/docs/reference/benchmarks-to-traces.md`
- **Embeddings phi for retrieval** (documentation): Retrieval DreamGym top-k ranks past steps by cosine similarity of an embedding phi state, action . The embedder that produces phi is chosen by HarnessConfig.embed provider an EmbedderKind and sized by HarnessConfig.embed dim . Evidence: `.agents/docs/reference/embeddings.md`
- **Playbook: hand-labeled meta-evals for improving automated components the judge method** (documentation): Playbook: hand-labeled meta-evals for improving automated components the judge method Evidence: `.agents/docs/reference/judge-meta-eval-playbook.md`
- **Methodology: trace-scaling + RAG-optimization experiments reproducible runbook** (documentation): Methodology: trace-scaling + RAG-optimization experiments reproducible runbook Evidence: `.agents/docs/reference/rag-scaling-methodology.md`
- **Runbook: building a world model from tau2 traces real Bedrock** (documentation): Runbook: building a world model from tau2 traces real Bedrock Evidence: `.agents/docs/reference/runbook-build-tau2-bedrock.md`
- **Iterating on BASE ENV PROMPT with replay fidelity** (documentation): Iterating on BASE ENV PROMPT with replay fidelity Evidence: `.agents/docs/research/base-env-prompt-iteration.md`
- **Benchmark results: reproducibility** (documentation): Dated snapshot June 2026 . These numbers were measured on the then-committed 66-trace tau2 corpus; the corpus has since grown to 1033 traces and the repo layout changed PR 38: paths are now examples/tau-bench/... , and the committed per-step report JSONs under benchmarks/results/ were removed . The methodology and the headline conclusion the GEPA lift is stable, not run-to-run luck stand; rerun the commands below for current numbers. Evidence: `.agents/docs/research/benchmark-results-reproducibility.md`
- **Concurrency scaling law — provenance data** (documentation): Concurrency scaling law — provenance data Evidence: `.agents/docs/research/concurrency_anthropic/NOTES.md`
- **Fidelity tiers — promoted** (documentation): The report lives at docs/research/world model findings.md ../../../docs/research/world model findings.md promoted 2026-07-10, PR 55 . Raw per-suite ladder JSONs remain here under fidelity tiers/ ./fidelity tiers/ . Evidence: `.agents/docs/research/fidelity-tiers.md`
- **GEPA optimization research** (documentation): This is the research surface for the harness's optimization trajectory: prompt optimization GEPA today, heavier training methods tomorrow. It exists to try optimization directions empirically — change a knob, measure reconstruction fidelity, record the result — rather than guessing. It is the experimental sibling of Iterating on BASE ENV PROMPT with replay fidelity which hand-tunes the base prompt and Design note: RAG-aware GEPA which explains the RAG-aware, leak-free evaluation every experiment here inherits . Directions not yet run live in Research directions not yet run ; the first completed sweep is written up in Trace scaling law . Evidence: `.agents/docs/research/gepa-optimization-research.md`
- **Benchmarking generate / execute / verify GEV** (documentation): Benchmarking generate / execute / verify GEV Evidence: `.agents/docs/research/gev-benchmarks.md`
- **Bench-EXEC scorecard: simulator vs real execution** (documentation): Bench-EXEC scorecard: simulator vs real execution Evidence: `.agents/docs/research/gev_bench_results/exec/exec_scorecard.md`
- **Bench-GEN labeling sheet tau-bench, 100 traces, budget 15** (documentation): Bench-GEN labeling sheet tau-bench, 100 traces, budget 15 Evidence: `.agents/docs/research/gev_bench_results/gen/labeling_sheet.md`
- **Bench-GEN blind manual labels: summary** (documentation): Bench-GEN blind manual labels: summary Evidence: `.agents/docs/research/gev_bench_results/gen/labels_summary.md`
- **Bench-GEN: scenario generation, first empirical run** (documentation): Bench-GEN: scenario generation, first empirical run Evidence: `.agents/docs/research/gev_bench_results/gen/report.md`
- **GEV benchmark: consolidated scorecard 2026-07-24** (documentation): GEV benchmark: consolidated scorecard 2026-07-24 Evidence: `.agents/docs/research/gev_bench_results/gev_scorecard.md`
- **Bench-VERIFY disagreement attribution** (documentation): Bench-VERIFY disagreement attribution Evidence: `.agents/docs/research/gev_bench_results/verify/disagreements.md`
- **Bench-VERIFY ground-truth inventory** (documentation): Bench-VERIFY ground-truth inventory Evidence: `.agents/docs/research/gev_bench_results/verify/ground_truth_notes.md`
- The remaining 20 evidence entries are in `AI_CONTEXT_PACK.json` or `EVIDENCE_INDEX.json`.

## Rules the Host AI Must Follow

- **Treat this asset as pre-work context, not a runtime environment.**: The AI Context Pack contains only an evidence-backed understanding of the project, not the project's executable state. Evidence: `docs/README.md`, `.agents/docs/README.md`, `.agents/docs/research/benchmark-grid/README.md`
- **When answering the user, distinguish what can be previewed from what can only be verified after install.**: The consumer value of the pre-install experience comes from reducing bad installs and misjudgments, not from pretending to be a real run. Evidence: `docs/README.md`, `.agents/docs/README.md`, `.agents/docs/research/benchmark-grid/README.md`

## Questions the User Should Answer First

- Which host AI or local environment do you plan to use it in?
- Do you just want to experience the workflow first, or are you ready to actually install?
- What matters most to you: install cost, output quality, or conflicts with your existing rules?

## Acceptance Checks

- Every capability claim can be traced back to a file path in evidence_refs.
- AI_CONTEXT_PACK.md does not package previews as a real run.
- The user can understand who it fits, what it can do, how to start, and the risk boundaries within 3 minutes.

---

## Doramagic Context Augmentation

The following sections strengthen the repository context for a host AI. Human Manual data is a reading route, and pitfall notes become operating constraints.

## Human Manual Outline

Usage rule: this is only a reading route and salience signal, not factual authority. Concrete claims must still return to repo evidence or Claim Graph.

Host AI hard rules:
- Do not treat page titles, section order, summaries, or importance values as factual project evidence.
- When explaining the Human Manual outline, state that it is only a reading route or salience signal.
- Capability, installation, compatibility, runtime state, and risk claims must cite repo evidence, source paths, or Claim Graph.

- **Introduction and Getting Started**: importance `high`
  - source_paths: README.md, pyproject.toml, wmo/__init__.py, wmo/cli/app.py, wmo/providers/registry.py
- **System Architecture and Core Modules**: importance `high`
  - source_paths: wmo/engine/world_model.py, wmo/engine/loader.py, wmo/engine/play.py, wmo/engine/build.py, wmo/harness/create.py
- **World Models, Optimization, and Distillation**: importance `high`
  - source_paths: wmo/optimize/routing.py, wmo/optimize/knn.py, wmo/optimize/judge.py, wmo/optimize/gepa.py, wmo/optimize/policy.py
- **Data Ingestion, Providers, and Platform Integrations**: importance `high`
  - source_paths: wmo/ingest/adapter.py, wmo/ingest/base.py, wmo/ingest/braintrust.py, wmo/ingest/langfuse.py, wmo/ingest/langsmith.py

## Repo Inspection Evidence

- repo_clone_verified: true
- repo_inspection_verified: true
- repo_commit: `1d2a54719356b3b7be61daf7ac7fefa9acd42e7b`
- inspected_files: `README.md`, `pyproject.toml`, `uv.lock`, `docs/README.md`, `docs/reference/closed_loop.md`, `docs/reference/connect-library.md`, `docs/reference/cost_quality_dial.md`, `docs/reference/distill.md`, `docs/reference/eval_grid.md`, `docs/reference/eval_suites.md`, `docs/reference/failover.md`, `docs/reference/harness_delta.md`, `docs/reference/ingest.md`, `docs/research/world_model_findings.md`, `packages/environment-capture/INTEGRATION.md`, `packages/environment-capture/README.md`, `packages/environment-capture/appworld/README.md`, `packages/environment-capture/appworld/backend/fetch_data.py`, `packages/environment-capture/appworld/backend/smoke.py`, `packages/environment-capture/appworld/backend/world_backend.py`

Host AI hard rules:
- Without repo_clone_verified=true, do not claim that the source code has been read.
- Without repo_inspection_verified=true, do not write README, docs, or package-file conclusions as facts.
- Without quick_start_verified=true, do not claim that the Quick Start path has run successfully.

## Doramagic Pitfall Constraints

These rules come from Doramagic discovery, validation, or compilation findings. The host AI must treat them as operating constraints, not background notes.

### Constraint 1: Capability evidence risk requires verification

- Trigger: README/documentation is current enough for a first validation pass.
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: capability.assumptions | https://news.ycombinator.com/item?id=49063454
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 2: Security or permission risk requires verification

- Trigger: no_demo
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: downstream_validation.risk_items | https://news.ycombinator.com/item?id=49063454
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 3: Security or permission risk requires verification

- Trigger: no_demo
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: risks.scoring_risks | https://news.ycombinator.com/item?id=49063454
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 4: Maintenance risk requires verification

- Trigger: issue_or_pr_quality=unknown。
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063454
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.

### Constraint 5: Maintenance risk requires verification

- Trigger: release_recency=unknown。
- Host AI rule: Reproduce the official install and quickstart path in an isolated environment.
- Why it matters: May increase setup, validation, or first-run risk for the user.
- Evidence: evidence.maintainer_signals | https://news.ycombinator.com/item?id=49063454
- Hard boundary: Do not present this pitfall as solved, verified, or ignorable unless later evidence explicitly closes it.