misterdev 0.3.1__tar.gz → 0.4.0__tar.gz

{misterdev-0.3.1/misterdev.egg-info → misterdev-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: misterdev
-Version: 0.3.1
+Version: 0.4.0
 Summary: An autonomous, extensible LLM build orchestrator that plans, edits, and verifies code across languages.
 Author-email: David Condrey <david@writerslogic.com>
 License-Expression: AGPL-3.0-or-later
@@ -150,7 +150,7 @@ misterdev keeps a durable, fingerprinted stream of its own real failures and run
 
 On the correctness side, misterdev works **reproduction-first**: for an issue-driven task it synthesizes a failing test from the acceptance criteria, **validates that the test actually fails on the clean tree** (a test that reproduces nothing is discarded rather than trusted), then drives the fix to turn it green — so the model edits toward a concrete, verified target instead of a description.
 
-**Two-timescale evolution** *(design; see [docs/two-timescale-evolution.md](docs/two-timescale-evolution.md))* takes the self-improvement further than a memoryless runtime agent can: the agent invents task-specific tools at runtime, and the ones that **prove they generalize** are consolidated — through the same held-out promotion gate — into a **persistent, best-per-capability tool library that future runs start from**. Fast loop explores; slow loop keeps the winners; the held-out gate keeps the library general rather than benchmark-overfit. Capability compounds across runs instead of being reinvented each task.
+**Two-timescale evolution** *(built; opt-in via `orchestrator.runtime_tooling`; see [docs/two-timescale-evolution.md](docs/two-timescale-evolution.md))* takes the self-improvement further than a memoryless runtime agent can. At **runtime**, the model may author a small task-specific helper tool that runs **sandboxed** (a hardened, network-less container — untrusted code never touches the host or the repo, and with no container engine the capability degrades off); its output feeds the edit. Every invented tool is then captured with the task's outcome into a **tool corpus** — a free byproduct of normal runs — and a deliberate promotion pass admits the tools whose success **generalizes** on a held-out task split (baseline drawn from the reproduction corpus) into a **persistent, best-per-capability tool library that future runs start from**. Fast loop invents; slow loop keeps only the winners; the same held-out gate that guards scaffold self-edits keeps the library general rather than benchmark-overfit. Capability **compounds across runs** instead of being reinvented each task — the memory the current top open-source scaffolds lack. Run the promotion pass with `python -m misterdev.core.evolution.tool_promotion <project>`.
 
 ### Extensibility
 
@@ -170,7 +170,7 @@ Gate-verified pass@1 on [Aider's polyglot benchmark](https://github.com/Aider-AI
 | Python | 8 / 10 | **80%** |
 | Rust | 7 / 10 | **70%** |
 
-A continuous stress run has solved **20/20** across the three languages with zero failures — including the exercises usually cited as hard (bowling, forth, arbitrary-precision decimal). Every solve is judged by the exercise's own hidden tests, not the model's say-so. Full numbers, methodology, and how to reproduce: **[docs/benchmark-results.md](docs/benchmark-results.md)**. Test suite: **1,897 passing** — **[docs/TESTING.md](docs/TESTING.md)**.
+A continuous stress run has solved **20/20** across the three languages with zero failures — including the exercises usually cited as hard (bowling, forth, arbitrary-precision decimal). Every solve is judged by the exercise's own hidden tests, not the model's say-so. Full numbers, methodology, and how to reproduce: **[docs/benchmark-results.md](docs/benchmark-results.md)**. Test suite: **1,941 passing** — **[docs/TESTING.md](docs/TESTING.md)**.
 
 ## CLI reference
 

{misterdev-0.3.1 → misterdev-0.4.0}/README.md

@@ -97,7 +97,7 @@ misterdev keeps a durable, fingerprinted stream of its own real failures and run
 
 On the correctness side, misterdev works **reproduction-first**: for an issue-driven task it synthesizes a failing test from the acceptance criteria, **validates that the test actually fails on the clean tree** (a test that reproduces nothing is discarded rather than trusted), then drives the fix to turn it green — so the model edits toward a concrete, verified target instead of a description.
 
-**Two-timescale evolution** *(design; see [docs/two-timescale-evolution.md](docs/two-timescale-evolution.md))* takes the self-improvement further than a memoryless runtime agent can: the agent invents task-specific tools at runtime, and the ones that **prove they generalize** are consolidated — through the same held-out promotion gate — into a **persistent, best-per-capability tool library that future runs start from**. Fast loop explores; slow loop keeps the winners; the held-out gate keeps the library general rather than benchmark-overfit. Capability compounds across runs instead of being reinvented each task.
+**Two-timescale evolution** *(built; opt-in via `orchestrator.runtime_tooling`; see [docs/two-timescale-evolution.md](docs/two-timescale-evolution.md))* takes the self-improvement further than a memoryless runtime agent can. At **runtime**, the model may author a small task-specific helper tool that runs **sandboxed** (a hardened, network-less container — untrusted code never touches the host or the repo, and with no container engine the capability degrades off); its output feeds the edit. Every invented tool is then captured with the task's outcome into a **tool corpus** — a free byproduct of normal runs — and a deliberate promotion pass admits the tools whose success **generalizes** on a held-out task split (baseline drawn from the reproduction corpus) into a **persistent, best-per-capability tool library that future runs start from**. Fast loop invents; slow loop keeps only the winners; the same held-out gate that guards scaffold self-edits keeps the library general rather than benchmark-overfit. Capability **compounds across runs** instead of being reinvented each task — the memory the current top open-source scaffolds lack. Run the promotion pass with `python -m misterdev.core.evolution.tool_promotion <project>`.
 
 ### Extensibility
 
@@ -117,7 +117,7 @@ Gate-verified pass@1 on [Aider's polyglot benchmark](https://github.com/Aider-AI
 | Python | 8 / 10 | **80%** |
 | Rust | 7 / 10 | **70%** |
 
-A continuous stress run has solved **20/20** across the three languages with zero failures — including the exercises usually cited as hard (bowling, forth, arbitrary-precision decimal). Every solve is judged by the exercise's own hidden tests, not the model's say-so. Full numbers, methodology, and how to reproduce: **[docs/benchmark-results.md](docs/benchmark-results.md)**. Test suite: **1,897 passing** — **[docs/TESTING.md](docs/TESTING.md)**.
+A continuous stress run has solved **20/20** across the three languages with zero failures — including the exercises usually cited as hard (bowling, forth, arbitrary-precision decimal). Every solve is judged by the exercise's own hidden tests, not the model's say-so. Full numbers, methodology, and how to reproduce: **[docs/benchmark-results.md](docs/benchmark-results.md)**. Test suite: **1,941 passing** — **[docs/TESTING.md](docs/TESTING.md)**.
 
 ## CLI reference
 

{misterdev-0.3.1 → misterdev-0.4.0}/misterdev/__init__.py

@@ -1,3 +1,3 @@
 """misterdev — an autonomous, extensible LLM build orchestrator."""
 
-__version__ = "0.3.1"
+__version__ = "0.4.0"

{misterdev-0.3.1 → misterdev-0.4.0}/misterdev/config.py

@@ -277,6 +277,16 @@ class OrchestratorSettings:
     # Each round is at most one model turn plus one tool call; the loop always
     # stops at this count even if the model keeps requesting tools.
     mcp_max_tool_rounds: int = 3
+    # Runtime tool-invention (two-timescale evolution P2): when on, the model may
+    # author a small task-specific helper tool that runs SANDBOXED (hardened,
+    # network-less container via ToolRunner; untrusted code never touches the host
+    # or the repo), and its output is fed into the edit context. Off by default —
+    # it is an untrusted-code-execution surface and requires a container engine;
+    # with no engine the invention degrades to a no-op (skip). Additive: off ->
+    # the edit path is byte-identical to today. Hard-capped by
+    # ``runtime_tooling_rounds``.
+    runtime_tooling: bool = False
+    runtime_tooling_rounds: int = 2
     # Optional governance layer: when on, a risk classifier gates risky commands
     # (destructive/irreversible/paid) at the command seam and an append-only
     # audit trail is written. Off by default and additive — when off the command

{misterdev-0.3.1 → misterdev-0.4.0}/misterdev/core/evolution/__init__.py

@@ -25,6 +25,10 @@ from .proposer import LLMProposer, build_instruction, parse_paths, parse_tag
 from .sandbox import SandboxEvaluator
 from .screen import MicroEvaluator, ScreenVerdict
 from .tool_library import ToolCandidate, ToolLibrary
+from .tool_corpus import ToolCorpus, ToolRecord, promote_from_corpus
+from .tool_promotion import run_tool_promotion
+from .tool_invention import invent_tool
+from .tool_runner import ToolRunner, ToolRunResult
 
 __all__ = [
     "MicroEvaluator",
@@ -47,6 +51,13 @@ __all__ = [
     "SandboxEvaluator",
     "ToolLibrary",
     "ToolCandidate",
+    "ToolRunner",
+    "ToolRunResult",
+    "invent_tool",
+    "ToolCorpus",
+    "ToolRecord",
+    "promote_from_corpus",
+    "run_tool_promotion",
     "LLMProposer",
     "build_instruction",
     "parse_paths",

misterdev-0.4.0/misterdev/core/evolution/tool_corpus.py

@@ -0,0 +1,199 @@
+"""The tool corpus — passive accumulation of self-authored tools and the task
+outcomes they rode along with, closing the two-timescale loop
+(``docs/two-timescale-evolution.md``).
+
+The runtime layer (:mod:`.tool_invention`) lets the model author a tool mid-task;
+live-SWE-agent throws that tool away when the task ends. This corpus keeps it:
+every invented tool is recorded with the task it ran on and whether that task
+resolved. The signal is a FREE byproduct of normal operation — no dedicated,
+paid A/B runs — which is the only economics a self-improvement loop can afford.
+As runs accumulate, each tool's per-task outcome history becomes dense enough for
+:func:`promote_from_corpus` to decide, through the SAME held-out generalization
+gate as scaffold evolution, which tools become permanent
+:class:`~.tool_library.ToolLibrary` entries that seed future runs.
+
+Honesty about the signal: a corpus outcome is CORRELATIONAL — the tool was present
+when the task resolved, not proven to have caused it — and the without-tool
+baseline is supplied by the caller (from the reproduction corpus or a prior), not
+fabricated here. So promotion is a defensible *ranking* of tools by held-out
+association, sharpening as data grows; it is not a controlled causal A/B. Per-task
+regressions are not attributed (no per-task counterfactual), so the promotion is
+association-positive, regression-agnostic — documented, not hidden.
+
+Persistence mirrors the reproduction corpus: one JSON file, atomic write,
+best-effort load that degrades to empty.
+"""
+
+import hashlib
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+from typing import Dict, List, Tuple
+
+from misterdev.logging_setup import setup_logger
+from misterdev.utils.file_utils import atomic_write
+
+logger = setup_logger(__name__)
+
+_MAX_TOOLS = 1000  # runaway guard; a real corpus is far smaller
+
+
+def _tool_id(source: str) -> str:
+    """A stable short id for a tool, keyed on its normalized source (so the same
+    tool re-authored with trivial whitespace differences collapses to one)."""
+    normalized = "\n".join(line.rstrip() for line in source.strip().splitlines())
+    return hashlib.sha256(normalized.encode("utf-8")).hexdigest()[:16]
+
+
+@dataclass
+class ToolRecord:
+    """One self-authored tool and its per-task outcome history."""
+
+    tool_id: str
+    niche: str
+    source: str
+    outcomes: Dict[str, bool] = field(default_factory=dict)  # task_id -> resolved
+    first_run: int = 0
+    last_run: int = 0
+
+    def score_on(self, task_ids) -> Tuple[int, int]:
+        """(resolved_count, total) over the given task ids present in this record."""
+        rel = [self.outcomes[t] for t in task_ids if t in self.outcomes]
+        return sum(1 for x in rel if x), len(rel)
+
+
+class ToolCorpus:
+    """Persistent per-tool outcome history backing held-out tool promotion."""
+
+    def __init__(self, path):
+        self.path = Path(path)
+
+    def _load(self) -> Tuple[Dict[str, ToolRecord], int]:
+        if not self.path.exists():
+            return {}, 0
+        try:
+            raw = json.loads(self.path.read_text(encoding="utf-8"))
+        except (json.JSONDecodeError, OSError):
+            return {}, 0
+        if not isinstance(raw, dict):
+            return {}, 0
+        run = int(raw.get("run", 0))
+        recs: Dict[str, ToolRecord] = {}
+        for item in raw.get("tools", []):
+            if not isinstance(item, dict) or not item.get("tool_id"):
+                continue
+            try:
+                recs[str(item["tool_id"])] = ToolRecord(
+                    tool_id=str(item["tool_id"]),
+                    niche=str(item.get("niche", "")),
+                    source=str(item.get("source", "")),
+                    outcomes={
+                        str(k): bool(v) for k, v in (item.get("outcomes") or {}).items()
+                    },
+                    first_run=int(item.get("first_run", 0)),
+                    last_run=int(item.get("last_run", 0)),
+                )
+            except (TypeError, ValueError):
+                continue
+        return recs, run
+
+    def _save(self, recs: Dict[str, ToolRecord], run: int) -> None:
+        ordered = sorted(recs.values(), key=lambda r: r.last_run, reverse=True)
+        kept = ordered[:_MAX_TOOLS]
+        payload = {"run": run, "tools": [asdict(r) for r in kept]}
+        try:
+            atomic_write(self.path, json.dumps(payload, indent=2))
+        except OSError as e:  # a learning stream never fails a build
+            logger.warning(f"Tool corpus save failed (non-fatal): {e}")
+
+    def record(self, source: str, niche: str, task_id: str, resolved: bool) -> str:
+        """Fold one (tool, task, outcome) observation in. Returns the tool id.
+
+        Best-effort: a persistence failure is logged, never raised. Last outcome
+        wins for a repeated (tool, task) pair, so a re-run updates rather than
+        double-counts.
+        """
+        if not source or not source.strip() or not task_id:
+            return ""
+        tid = _tool_id(source)
+        recs, run = self._load()
+        run += 1
+        rec = recs.get(tid)
+        if rec is None:
+            rec = ToolRecord(tool_id=tid, niche=niche, source=source, first_run=run)
+            recs[tid] = rec
+        rec.niche = niche or rec.niche
+        rec.outcomes[task_id] = resolved
+        rec.last_run = run
+        self._save(recs, run)
+        return tid
+
+    def records(self) -> List[ToolRecord]:
+        return list(self._load()[0].values())
+
+    def stats(self) -> Dict[str, int]:
+        recs = self.records()
+        obs = sum(len(r.outcomes) for r in recs)
+        return {"tools": len(recs), "observations": obs}
+
+
+def promote_from_corpus(
+    corpus: ToolCorpus,
+    library,
+    *,
+    baseline_rate,
+    min_observations: int = 5,
+    holdout_fraction: float = 0.3,
+    noise_band: float = 0.0,
+) -> List[str]:
+    """Promote corpus tools that GENERALIZE into the library; return promoted ids.
+
+    For each tool with at least ``min_observations`` task outcomes, split its tasks
+    into disjoint DERIVE/HOLDOUT pools (stable per-task hash), score the tool's
+    with-tool resolve-rate on each, and admit it through the library's held-out
+    gate against the WITHOUT-tool baseline. A tool is promoted only if its
+    association with success holds on the tasks it was NOT selected on — the same
+    anti-overfit ratchet scaffold evolution uses.
+
+    ``baseline_rate`` is the without-tool resolve-rate: a float applied to every
+    tool, or a callable ``baseline(niche) -> float`` so the baseline can come
+    per-niche from the reproduction corpus (see ``tool_promotion``). Pure: no I/O
+    beyond the corpus/library the caller passes.
+    """
+    from .fitness import FitnessScore
+    from .holdout import split_tasks
+    from .tool_library import ToolCandidate
+
+    baseline_of = (
+        baseline_rate if callable(baseline_rate) else (lambda _n: baseline_rate)
+    )
+    promoted: List[str] = []
+    for rec in corpus.records():
+        base = max(0.0, min(1.0, float(baseline_of(rec.niche))))
+        task_ids = sorted(rec.outcomes)
+        if len(task_ids) < min_observations:
+            continue
+        derive_ids, holdout_ids = split_tasks(task_ids, holdout_fraction)
+        dr, dt = rec.score_on(derive_ids)
+        hr, ht = rec.score_on(holdout_ids)
+        if dt == 0 or ht == 0:
+            continue
+        candidate = ToolCandidate(
+            id=rec.tool_id,
+            niche=rec.niche,
+            source=rec.source,
+            resolved=dr,
+            total=dt,
+            cost=0.0,
+            provenance=f"corpus:{len(task_ids)} tasks",
+        )
+        decision = library.consider(
+            candidate,
+            derive=FitnessScore(dr, dt, 0.0),
+            derive_base=FitnessScore(round(base * dt), dt, 0.0),
+            holdout=FitnessScore(hr, ht, 0.0),
+            holdout_base=FitnessScore(round(base * ht), ht, 0.0),
+        )
+        if decision.promote:
+            promoted.append(rec.tool_id)
+    return promoted

misterdev-0.4.0/misterdev/core/evolution/tool_invention.py

@@ -0,0 +1,140 @@
+"""Runtime tool-invention: let the model author a task-specific helper tool and
+run it sandboxed, feeding the output back — the runtime half of two-timescale
+evolution (``docs/two-timescale-evolution.md``) and the capability that sits #1
+open on SWE-bench (live-SWE-agent).
+
+Additive and best-effort, mirroring
+:mod:`misterdev.core.integration.mcp_gather`: the model MAY emit a ``tool`` block
+(Python source) and an optional ``stdin`` block; the source runs via the hardened,
+network-less :class:`~misterdev.core.evolution.tool_runner.ToolRunner` (untrusted
+code never touches the host or the repo), and its output is returned as a context
+block the executor prepends to the edit context. A model that wants no tool
+replies ``NO_TOOL`` and the result is ``""`` — byte-identical to the no-tooling
+path. The loop is hard-capped so a model can author, see the output, and refine
+once or twice, then stop.
+
+Never raises into the build: no runner, no sandbox, a model error, or an
+unparseable reply all degrade to whatever was produced so far (usually nothing).
+"""
+
+import re
+from typing import Callable, List, Optional, Protocol
+
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+# The model authors source in a ```tool (or ```python-tool) fence, with optional
+# stdin in a ```stdin fence. Searched (not anchored) and DOTALL so the blocks may
+# span lines and sit amid prose.
+_TOOL_RE = re.compile(r"```(?:tool|python-tool)\s*\n(.*?)```", re.DOTALL)
+_STDIN_RE = re.compile(r"```stdin\s*\n(.*?)```", re.DOTALL)
+
+_HEADER = "## Tools you authored and ran (sandboxed) to inform the edit\n"
+
+_INSTRUCTION = (
+    "You MAY author ONE small Python helper tool to compute or verify something "
+    "for this task before you edit — for example a reference calculation, a "
+    "parser, or a checker. It runs SANDBOXED: no network, no filesystem or "
+    "repository access, bounded time and memory. It is a pure function — supply "
+    "any input it needs yourself.\n\n"
+    "To author a tool, emit its source in a fenced ```tool block, and (optionally) "
+    "its stdin in a fenced ```stdin block. Its stdout is returned to you so you "
+    "can use the result in your edit. To author no tool and proceed straight to "
+    "editing, reply with NO_TOOL.\n"
+)
+
+
+class _ToolRunnerLike(Protocol):
+    def run(self, source: str, stdin: str = ""): ...
+
+
+def _render(result) -> str:
+    """The tool's output for the model: stdout on success, else stderr/detail."""
+    body = (result.stdout or "").strip() or (result.stderr or "").strip()
+    return body or "(no output)"
+
+
+def invent_tool(
+    runner: Optional[_ToolRunnerLike],
+    ask: Callable[[str], Optional[str]],
+    *,
+    task_description: str = "",
+    error_context: str = "",
+    max_rounds: int = 2,
+    sink: Optional[List[str]] = None,
+    seeds: Optional[List[str]] = None,
+) -> str:
+    """Run the bounded tool-invention loop; return the invented-tools context block.
+
+    ``runner`` is a :class:`ToolRunner` (may be ``None``). ``ask`` takes a prompt
+    and returns the model's reply. Each round the model may author one tool; it is
+    run sandboxed and its output fed into the next round's prompt. ``max_rounds``
+    hard-caps iterations (< 1 disables). Returns a context string suitable for
+    prepending to the edit context, or ``""`` when no tool was authored or run.
+    """
+    if runner is None or max_rounds < 1:
+        return ""
+    invented: List[str] = []
+    for round_idx in range(max_rounds):
+        prompt = _INSTRUCTION
+        if seeds:
+            prompt += (
+                "\n## Proven tools from past runs — reuse or adapt one if it fits\n"
+                + "\n\n".join(f"```python\n{s}\n```" for s in seeds)
+                + "\n"
+            )
+        if task_description:
+            prompt += f"\n## Task\n{task_description}\n"
+        if error_context:
+            prompt += (
+                "\n## The current failure you may write a tool to diagnose\n"
+                f"{error_context}\n"
+            )
+        if invented:
+            prompt += "\n" + _HEADER + "\n\n".join(invented) + "\n"
+
+        try:
+            reply = ask(prompt)
+        except Exception as e:  # a model/client failure must not sink the build
+            logger.debug(
+                f"tool-invention: model call failed round {round_idx + 1}: {e}"
+            )
+            break
+
+        m = _TOOL_RE.search(reply or "")
+        if m is None:
+            logger.info(
+                f"tool-invention: model authored no tool in round {round_idx + 1}; "
+                "stopping."
+            )
+            break
+        source = m.group(1).strip()
+        if not source:
+            break
+        sm = _STDIN_RE.search(reply or "")
+        stdin = sm.group(1) if sm else ""
+
+        result = runner.run(source, stdin)
+        if result.status == "skip":
+            logger.info("tool-invention: no sandbox available; tool not run.")
+            break
+        if sink is not None:
+            sink.append(source)  # captured for the tool corpus (P2c)
+        logger.info(
+            f"tool-invention round {round_idx + 1}/{max_rounds}: ran a tool "
+            f"({len(source)}B source) -> {result.status}"
+        )
+        invented.append(
+            f"### tool (round {round_idx + 1})\n```python\n{source}\n```\n"
+            f"output [{result.status}]:\n{_render(result)}"
+        )
+
+    if not invented:
+        return ""
+    return (
+        "\n\n"
+        + _HEADER
+        + "You wrote and ran these tools; use their results in your edit.\n\n"
+        + "\n\n".join(invented)
+    )

misterdev-0.4.0/misterdev/core/evolution/tool_promotion.py

@@ -0,0 +1,101 @@
+"""The tool-promotion pass — the deliberate step that CLOSES the two-timescale
+loop (``docs/two-timescale-evolution.md``).
+
+Capture is automatic (every build folds invented tools + outcomes into the tool
+corpus). Promotion is deliberate, like the scaffold-evolution run: this pass reads
+the tool corpus, derives the WITHOUT-tool baseline PER NICHE from the reproduction
+corpus (the resolve-rate on comparable tasks with no self-authored tool), and
+admits the tools whose with-tool success-association holds on a held-out task
+split into the persistent :class:`~.tool_library.ToolLibrary`. Promoted tools then
+seed future runs, so capability compounds.
+
+The two corpora together are the fitness signal that a single run cannot give:
+reproduction corpus = without-tool outcomes, tool corpus = with-tool outcomes,
+their difference = a tool's (as-causal-as-observational-data-allows) effect. It is
+correlational, not a controlled A/B — so this ranks tools by held-out association
+and sharpens as data accumulates; it does not certify causation. Pure of LLM/cost:
+it only reads the two JSON corpora and writes the library.
+
+CLI: ``python -m misterdev.core.evolution.tool_promotion <project_path>``.
+"""
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Dict
+
+from misterdev.core.evolution.tool_corpus import ToolCorpus, promote_from_corpus
+from misterdev.core.evolution.tool_library import ToolLibrary
+from misterdev.core.learning.reproduction import ReproductionCorpus
+from misterdev.logging_setup import setup_logger
+
+logger = setup_logger(__name__)
+
+
+def run_tool_promotion(
+    project_path,
+    *,
+    default_baseline: float = 0.5,
+    min_observations: int = 5,
+    holdout_fraction: float = 0.3,
+    noise_band: float = 0.0,
+) -> Dict:
+    """Run the promotion pass for a project; return a summary dict.
+
+    ``default_baseline`` is the prior used for a niche the reproduction corpus has
+    no data on (so an empty baseline never spuriously promotes). Never raises: a
+    missing/corrupt corpus degrades to "nothing promoted".
+    """
+    ev = Path(project_path) / ".orchestrator" / "evolution"
+    corpus = ToolCorpus(ev / "tool_corpus.json")
+    repro = ReproductionCorpus(ev / "reproduction.json")
+    library = ToolLibrary(ev / "tool_library.json")
+
+    def baseline_for(niche: str) -> float:
+        rate = repro.resolve_rate(niche)
+        return rate if rate is not None else default_baseline
+
+    promoted = promote_from_corpus(
+        corpus,
+        library,
+        baseline_rate=baseline_for,
+        min_observations=min_observations,
+        holdout_fraction=holdout_fraction,
+        noise_band=noise_band,
+    )
+    stats = corpus.stats()
+    logger.info(
+        f"Tool promotion: {len(promoted)} promoted from {stats['tools']} tool(s) / "
+        f"{stats['observations']} observation(s); library now {len(library.elites())}."
+    )
+    return {
+        "promoted": promoted,
+        "corpus": stats,
+        "library_size": len(library.elites()),
+    }
+
+
+def main(argv=None) -> int:
+    parser = argparse.ArgumentParser(prog="misterdev.core.evolution.tool_promotion")
+    parser.add_argument("project_path", help="project whose .orchestrator/ to promote")
+    parser.add_argument("--default-baseline", type=float, default=0.5)
+    parser.add_argument("--min-observations", type=int, default=5)
+    parser.add_argument("--holdout-fraction", type=float, default=0.3)
+    parser.add_argument("--noise-band", type=float, default=0.0)
+    args = parser.parse_args(argv)
+    result = run_tool_promotion(
+        args.project_path,
+        default_baseline=args.default_baseline,
+        min_observations=args.min_observations,
+        holdout_fraction=args.holdout_fraction,
+        noise_band=args.noise_band,
+    )
+    sys.stdout.write(
+        f"promoted {len(result['promoted'])} tool(s); "
+        f"corpus={result['corpus']}; library={result['library_size']}\n"
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())