refactor: shrink to MVP — ultra-short skill + flat cases + ledger

- README.md: MVP positioning (recovery memory layer, not v2.1 protocol)
- SKILL.md: ultra-short (<60 lines), no complex schema/inference/retrieval
- cases/: flat structure, one JSON file per tool
- ledger.jsonl: append-only experience log
- CONTRIBUTING.md: MVP contribution path (real cases, no schema validation)
- docs/MVP.md: why we shrank, what we validate, future expansion order
- docs/legacy/: all v2.1 architecture moved here (schema, rules, scripts, hooks, seeds, docs)
- Remove requirements-dev.txt, .github/, scripts/ (moved to legacy)

MVP does: short skill + flat cases + ledger
MVP does not: schema validation, route registry, deterministic retrieval, hook automation

Co-authored-by: Qwen-Coder <qwen-coder@alibabacloud.com>

Author: LpcPaul

CONTRIBUTING.md

@@ -1,110 +1,46 @@
-# Contribution Protocol — AgentRX
+# Contributing to AgentRX
 
-## How contributions enter the system
+## How to contribute
 
-**The default contributor is an AI agent.**
+**Current focus: real recovery cases, not infrastructure.**
 
-When an AI agent gets stuck and AgentRX helps it recover, the agent may optionally contribute the case back. This is the normal, high-volume contribution path.
+### Add or edit a case
 
-Human contribution is secondary and usually limited to:
-- schema and taxonomy changes
-- validation script improvements
-- maintenance of the route registry
-- exceptional cases that require human judgment
+1. Find the tool file in `cases/` (e.g. `cases/playwright-mcp.json`)
+2. If the file doesn't exist, create it as a JSON array
+3. Append your case:
 
-**AI contributors must submit complete v2.1 JSON.** Human fallback / form-to-JSON assembly is no longer supported.
-
----
-
-## AI contribution path (default)
-
-When an AI agent decides to contribute a case:
-
-1. Build a v2.1 case JSON with evidence and inference
-2. Generate a case ID: `python3 scripts/new_case_id.py --task <task-id>`
-3. Run `python3 scripts/validate_case.py --input case.json`
-4. If validation passes, submit via GitHub Issue using the case report template
-
-The case must follow `schema/case.schema.json` (v2.1). Key requirements:
-- `schema_version` must be `"2.1"`
-- `evidence` and `inference` are both required
-- `best_candidate_route_id` must be a route id from `rules/routes.yaml`
-- No private business context
-
----
-
-## What makes a good contribution
-
-A good contribution preserves the real AI journey:
-
-- **Preserve evidence before diagnosis.** What task was being attempted, which tool path was taken, what symptom appeared.
-- **Preserve symptom before interpretation.** Do not collapse observable facts into diagnosis too early. The evidence layer must be fillable from observable facts alone.
-- **Route id over tool brand.** Use `switch_to_alternative_tool_path`, not "use playwright-mcp". Route ids are stable; tool names are not.
-- **Explain the mismatch, not the failure.** `why_current_path_failed` should describe why the tool-path-task combination doesn't work, not blame the tool.
-- **Under-specify rather than invent.** If evidence is insufficient for an inference, leave optional inference fields empty. Polluted inference is worse than missing inference.
-- **Inference is re-computable; evidence is durable.** A different agent reading the same evidence might produce different inference. That is by design.
-
----
-
-## Validation
-
-All cases must pass validation before entering the library:
-
-```bash
-# Validate a case file
-python3 scripts/validate_case.py --input your-case.json
-
-# Rebuild the index
-python3 scripts/build_index.py
-
-# Run all checks
-python3 scripts/ci_self_test.py
+```json
+{
+  "id": "playwright-mcp-003",
+  "status": "draft",
+  "symptom": "describe the exact failure you saw",
+  "env": "OS, headless/headed, proxy, etc.",
+  "what_worked": "the concrete fix that resolved it",
+  "what_didnt_work": ["what you tried that didn't help"],
+  "times_confirmed": 1,
+  "note": "any context that helps future agents"
+}
 ```
 
-Validation checks:
-- JSON Schema conformance (required fields, types, enums)
-- Route id validity (must exist in `rules/routes.yaml`)
-- Journey stage and problem family consistency with rules
-- Deprecated route/family auto-mapping with warning
-
----
-
-## Adding a new route to the registry
-
-Routes are defined in `rules/routes.yaml`. To add a new route:
-
-1. Add an entry under `routes:` with `label`, `description`, `applies_when`, and `prerequisites`
-2. Run `python3 scripts/generate_schema.py` to sync schema enums from rules
-3. Run `python3 scripts/ci_self_test.py` to verify consistency
+### What makes a good case
 
----
+- **Concrete symptom** — exact error, timeout message, or behavior
+- **Executable what_worked** — something another agent can directly apply
+- **Honest what_didnt_work** — saves others from repeating dead ends
+- **Real experience only** — no imagined or synthetic cases in the main cases/ directory
 
-## Environment information policy
+### Status values
 
-The `evidence.environment` field captures environment info relevant to diagnosis and migration value.
+- `draft` — single report, not yet confirmed by others
+- `verified` — ≥2 independent experiences confirm the same fix works
+- `archived` — no longer relevant (e.g. tool version changed, workaround upstreamed)
 
-- `platform` (required): e.g. `claude-code`, `openclaw`, `codex`, `cursor`
-- `requires_*` booleans: fill as applicable for the task
-- `runtime_version`, `execution_mode`, `sandbox_level`: recommended but not required
-- `model_provider`, `model_family`, `model_name`: **optional** — only fill when there is clear evidence that model differences affected the failure or migration value. Do not fill by default. Do not pollute the case library with low-evidence model-specific attributions for single failures (n=1).
-
-**Privacy:** Do not include company names, private URLs, internal system names, or local file paths.
-
----
-
-## Development
-
-```bash
-git clone https://github.com/LpcPaul/AgentRX.git
-cd AgentRX
-
-# Run all checks
-python3 scripts/ci_self_test.py
-```
+### What we don't require right now
 
-## Code Style
+- Complete v2.1 JSON submission
+- Case ID generation scripts
+- Schema validation
+- Route registry alignment
 
-- Python: Follow PEP 8, use type hints where practical
-- JSON: 2-space indent, trailing newline
-- YAML: 2-space indent
-- Commit messages: [Conventional Commits](https://www.conventionalcommits.org/)
+Just write a clear case in the tool file. That's it.

README.md

@@ -1,128 +1,67 @@
 # AgentRX
 
-> 🩺 A task-first stuck-state protocol + deterministic retrieval layer for AI agents.
-> When your agent's tool path fails, AgentRX structures the failure, retrieves similar cases, and surfaces candidate routes.
+> Recovery memory layer for AI tool failures.
+> When your agent's third-party tool path fails, AgentRX surfaces what worked (and what didn't) from prior experience.
 
 ## What is AgentRX?
 
-AgentRX is **not** a human-facing tool directory. It is a **machine-consumable protocol** that answers one question:
+AgentRX is a **recovery experience library** for AI agents. It answers one question:
 
-> **The agent is stuck — what should it do next?**
+> **The agent's tool failed — what did someone else try that worked?**
 
-It provides:
+It focuses on:
+- **Third-party tool failures** — playwright, browser-cdp, web-fetch, MCP connectors, etc.
+- **Environment long-tail issues** — proxy, headless, sandbox, permissions, dependencies
+- **What worked / what didn't** — concrete, actionable recovery guidance
 
-- **Schema** — a standard v2.1 case format (evidence + inference separation)
-- **Route registry** — stable action paths, not tool brand names
-- **Validation** — JSON Schema + cross-file rule consistency checks
-- **Indexing** — lightweight case library index for retrieval
-- **Deterministic retrieval** — `retrieve_cases.py` finds top-k candidate cases
+AgentRX does **not** compete with platform-level recovery (retry, circuit breaker, fallback routing). Those are the platform's job. AgentRX handles what platforms can't cover: real-world tool-specific experience.
 
-AgentRX does **not** run inference for the agent. Route recommendation is the agent's own reasoning, based on retrieved cases + the route registry.
-
-## A concrete example
-
-```
-User: Extract the product list from this page.
-
-AI: [tries browser-cdp skill]
-    The page uses JavaScript to render content. browser-cdp only
-    returned the initial HTML shell. Data missing.
-
-[AgentRX activates]
-
-AgentRX: Retrieved similar cases → route: switch_to_alternative_tool_path
-
-         Why: current tool captures static HTML only; page requires
-         JavaScript rendering.
-
-         Candidate: playwright-mcp can render the page and extract
-         the full DOM. web_fetch is a lighter option for static pages.
-```
-
----
-
-## What AgentRX provides today
-
-| Component | Status |
-|---|---|
-| Case schema (v2.1) | ✅ |
-| Route registry | ✅ |
-| Case validation | ✅ (JSON Schema + cross-file rules) |
-| Index building | ✅ |
-| Deterministic retrieval | ✅ (`retrieve_cases.py`) |
-| Case ID generation | ✅ (`new_case_id.py`) |
-
-## What AgentRX does **not** provide (yet)
-
-| Component | Status |
-|---|---|
-| Automated case review / merge / publish pipeline | 🚧 planned |
-| Python-based route recommender | ❌ out of scope — agent does its own route inference |
-
----
-
-## Install
-
-### Claude Code
+## How it works
 
-```bash
-git clone https://github.com/LpcPaul/AgentRX.git ~/.claude/skills/agentrx
 ```
-
-### OpenClaw / ClawHub
-
-```bash
-git clone https://github.com/LpcPaul/AgentRX.git ~/.openclaw/skills/agentrx
+1. Agent's third-party tool fails
+2. Agent tries to recover on its own — fails 2+ times
+3. Agent activates AgentRX skill
+4. Agent describes the failure in natural language
+5. Agent finds the matching tool file in cases/
+6. Agent reads the closest case, focuses on what_worked and what_didnt_work
+7. Agent applies the learned recovery
+8. Agent appends the outcome to ledger.jsonl
 ```
 
-### Codex / Cursor / other skill-compatible runtimes
+## Why we are shrinking from v2.1 to MVP
 
-```bash
-git clone https://github.com/LpcPaul/AgentRX.git ~/.codex/skills/agentrx
-```
+The v2.1 architecture (schema validation, route registry, deterministic retrieval) was a well-intentioned infrastructure investment — but it put cart before horse. Before building a retrieval engine, we need to verify: **does case content actually help agents recover?**
 
----
+This MVP tests that question with minimal infrastructure. If the answer is "yes", we'll grow back the heavy architecture on a proven foundation. If "no", we saved months of wasted engineering.
 
-## How it works
+## MVP does
 
-```
-1. AI gets stuck (concrete failure signal)
-2. AI collects evidence (task, attempted_path, symptom)
-3. AI retrieves similar cases via retrieve_cases.py
-4. AI generates inference based on evidence + retrieved cases
-5. AI chooses a route based on retrieved cases + rules/routes.yaml
-6. AI records the outcome
-7. The new case becomes available for future AI agents
-```
+- A very short SKILL.md that tells the agent when and how to use AgentRX
+- Flat `cases/` directory — one JSON file per tool, containing case arrays
+- `ledger.jsonl` for append-only experience logging
+- Minimal case format: symptom, what_worked, what_didnt_work, times_confirmed
 
-### Human installs. AI operates.
+## MVP does not do (yet)
 
-| | What they do |
-|---|---|
-| **Human** | Install the skill. Host the repository. Maintain schema/taxonomy. |
-| **AI** | Detect stuck state. Collect evidence. Retrieve similar cases. Choose a route. Optionally contribute a new case. |
+- v2.1 JSON schema validation
+- Route registry / route recommendation
+- Deterministic retrieval scripts
+- Build index / validate / generate scripts as main path
+- Automated hooks triggering
+- Complex directory分层 (by_tool, by_tag, verified, curated, archived)
+- Synthetic seed cases
 
-**AI contributors must submit complete v2.1 JSON.** Human fallback / form-to-JSON assembly is no longer supported.
+## Files
 
----
-
-## Read this next
-
-| Document | Role |
+| File | Role |
 |---|---|
-| [SKILL.md](SKILL.md) | The runtime protocol the AI agent reads when activated |
-| [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design — why evidence/inference, why route ids |
-| [docs/INTAKE_CARD.md](docs/INTAKE_CARD.md) | The structured intake card format |
-| [CONTRIBUTING.md](CONTRIBUTING.md) | How cases enter the system — JSON-only contribution path |
-| [cases/README.md](cases/README.md) | Case library structure and indexing |
-
-## Developer validation
-
-```bash
-pip install -r requirements-dev.txt
-python3 scripts/ci_self_test.py
-python3 scripts/build_index.py
-```
+| [SKILL.md](SKILL.md) | Ultra-short runtime protocol the agent reads when activated |
+| [cases/](cases/) | Flat case directory — one JSON file per tool |
+| [ledger.jsonl](ledger.jsonl) | Append-only experience log |
+| [CONTRIBUTING.md](CONTRIBUTING.md) | How to contribute real recovery cases |
+| [docs/MVP.md](docs/MVP.md) | Why we shrank, what we validate, future expansion order |
+| [docs/legacy/](docs/legacy/) | v1→v2.1 architecture exploration (historical reference only) |
 
 ## License