claudescientist 5.1.0__tar.gz

claudescientist-5.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 whenpoem
+
+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.

claudescientist-5.1.0/PKG-INFO

@@ -0,0 +1,262 @@
+Metadata-Version: 2.4
+Name: claudescientist
+Version: 5.1.0
+Summary: Research-agent augmentation layer for Claude Code with SQLite memory, verification MCPs, a proof trunk with NL workflow + Lean reinsurance, and a Textual cockpit TUI.
+Keywords: claude-code,mcp,research,sqlite,textual,tui,proof,lean,statistics,formal-methods
+Author: whenpoem
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: fastmcp>=3.2.4
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.13.1
+Requires-Dist: textual>=8.2,<9.0
+Requires-Dist: questionary>=2.0
+Requires-Dist: sentence-transformers>=2.2 ; extra == 'all'
+Requires-Dist: openai>=1.0 ; extra == 'all'
+Requires-Dist: sentence-transformers>=2.2 ; extra == 'embed-local'
+Requires-Dist: openai>=1.0 ; extra == 'embed-openai'
+Requires-Dist: sentence-transformers>=2.2 ; extra == 'proof'
+Requires-Python: >=3.11
+Project-URL: Repository, https://github.com/whenpoem/aiscientist
+Project-URL: Issues, https://github.com/whenpoem/aiscientist/issues
+Provides-Extra: all
+Provides-Extra: embed-local
+Provides-Extra: embed-openai
+Provides-Extra: proof
+Description-Content-Type: text/markdown
+
+# ClaudeScientist
+
+**A research co-pilot that remembers, verifies, and lets you steer.**
+
+[![version](https://img.shields.io/badge/version-v5.1.0-blue)](https://github.com/whenpoem/aiscientist/releases) [![python](https://img.shields.io/badge/python-%E2%89%A53.11-3776AB?logo=python&logoColor=white)](https://www.python.org/) [![CI](https://github.com/whenpoem/aiscientist/actions/workflows/ci.yml/badge.svg)](https://github.com/whenpoem/aiscientist/actions/workflows/ci.yml) [![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+
+> 中文版本: [README.zh-CN.md](README.zh-CN.md)
+
+ClaudeScientist plugs into Claude Code or Codex and adds what most AI scientist systems leave out: it remembers what you've tried, verifies your numbers before you publish them, and gives you a live terminal dashboard where you can watch the research unfold and step in at any time.
+
+You give the agent a research question. It generates hypotheses, ranks them in a tournament, runs experiments with built-in safety checks, and tracks provenance for every number it produces. You watch the whole process in a second terminal and can reject, redirect, or approve at any point.
+
+**Current version**: v5.1.0 is a trust-calibration and portability release.
+Bradley-Terry rankings are refit from the complete ledger and no longer depend
+on comparison order; their intervals are honestly labelled as uncalibrated
+approximations. Bonferroni families are fixed when locked. Every central run
+automatically fingerprints code, inputs, Git state, dependencies, seeds, and
+runtime. A public Codex plugin bundles the core MCPs, Skills, hooks, and local
+Cockpit without tying them to this repository's working directory. The v5.0
+activity-streaming Cockpit remains intact; see
+[ADR 0011](docs/adr/0011-cockpit-activity-streaming.md).
+
+**v4.2.0 features retained** (see [retrospective-v4.2.md](docs/retrospective-v4.2.md)): tab grouping into Cross / Empirical / Proof, collapsible detail sections, pane-scoped `w`/`i`/`t` keys, the multi-provider vector backend (DashScope / Jina / Voyage / GLM tested via [ADR 0010](docs/adr/0010-multi-provider-embeddings.md), default local `Qwen/Qwen3-Embedding-0.6B`), reports-as-files (closure / draft / diagnostic / portfolio / cascade) per [ADR 0009](docs/adr/0009-reports-as-files-monitoring-as-tui.md), and the cold-start Welcome screen. See [architecture.md §13](docs/architecture.md#13-core-vs-domain-trunks-v40) for the two-trunk split.
+
+## What it looks like
+
+Open two terminals side by side. That's the whole UI.
+
+<picture>
+  <img alt="Cockpit TUI screenshot" src="docs/assets/image2.png" width="800">
+</picture>
+
+*The cockpit TUI — hypothesis tree, evidence, ratings, and event stream in one terminal.*
+
+The two terminals don't talk to each other directly — they both read and write the same SQLite file. This is the central design choice: every module collaborates through a shared database, not over the network.
+
+| Role | Where | What it does |
+|---|---|---|
+| **Claude Code / Codex** | Terminal A | Drives the research: understands your question, calls tools, writes and runs code |
+| **MCP servers** | Background | Provide the tools the agent calls — memory, verification, literature search, proof generation |
+| **Hooks** | Auto-loaded at startup | Run safety checks before/after every tool call (block data leaks, log provenance) |
+| **Cockpit TUI** | Terminal B | Shows live state; lets you approve, reject, or redirect hypotheses |
+| **SQLite** | `.research-agent/state.db` | The single file that holds all state: hypotheses, evidence, ratings, metrics, events |
+
+## What you can do with it
+
+- **Track your research thinking.** Every hypothesis, piece of evidence, and branching decision lives in a persistent graph. Papers you read along the way are compressed and searchable. Come back next week — it's all there. Want to revisit a direction you pruned? Run a counterfactual replay without touching the live state.
+- **Rank competing ideas.** A Bradley-Terry tournament compares hypotheses
+  head-to-head and produces an order-invariant leaderboard with explicitly
+  uncalibrated approximate posterior intervals. Use it with comparison coverage
+  and domain evidence, not as a significance test.
+- **Lock your goalposts before experimenting.** Preregistration makes you commit to a metric, direction, and threshold before you see results. Multiple-comparison correction is applied automatically.
+- **Make your numbers trustworthy.** Every reported number gets checked: Is it reproducible across random seeds? Which files produced it? Has anything changed since? Baseline comparisons are checked for fair compute budgets. A reviewer agent blocks any unverified claim from reaching a writeup.
+- **Catch mistakes before they compound.** A failure ledger remembers every debugging session. Next time you hit a similar problem, the system surfaces how you fixed it before.
+- **Watch and steer in real time.** The cockpit TUI shows the hypothesis tree, ratings, and event stream live. Press a key to reject a bad hypothesis or inject a note — interventions are picked up at the next turn.
+- **Generate and verify statistical proofs** *(v4.0).* A proof trunk handles drafting, segmentation, diagnosis against known error patterns, and optional Lean 4 formal verification.
+
+## Quick start
+
+### Install the public Codex plugin
+
+The plugin works from any research project; Codex does not need to start inside
+the ClaudeScientist source checkout.
+
+```powershell
+uv tool run --from claudescientist==5.1.0 claudescientist setup --scope user
+```
+
+This command installs the marketplace at the matching `v5.1.0` Git tag and
+then installs the plugin. The Python package and Git tag must both be published
+before this public command can work; source-checkout testing does not replace
+that release step. See [docs/setup-codex-plugin.md](docs/setup-codex-plugin.md)
+for the equivalent manual commands.
+
+Start a new Codex task after installation. Approve/trust the plugin hooks when
+Codex asks. MCP monitoring works without hook trust, but Cockpit interventions
+remain **monitor-only** until the hooks are trusted.
+
+From the research project you want to monitor:
+
+```powershell
+uv tool run --from claudescientist==5.1.0 claudescientist doctor --workspace .
+uv tool run --from claudescientist==5.1.0 claudescientist cockpit --workspace . --lang zh
+```
+
+Each project keeps independent state in its own `.research-agent/state.db`.
+The public plugin enables only the four local core MCPs (`memory`, `verify`,
+`prove`, `cockpit`). arXiv, OpenAlex, and Lean remain explicit opt-ins.
+
+### Develop from this checkout
+
+Install and run the setup wizard:
+
+```powershell
+uv sync
+uv run python -m claudescientist.setup
+```
+
+The wizard walks you through AI client selection (`claude`, `codex`, or
+`both`), embedding backend, proof corpus seeding, held-out directory, Lean
+toolchain, and auto-prune — all in one pass. Run it again any time; it skips
+steps that are already done.
+
+For non-interactive setup, set `CLAUDESCIENTIST_SETUP_AGENT_HOST=codex` or
+`CLAUDESCIENTIST_SETUP_AGENT_HOST=both`. Codex support is project-local: setup
+generates `.codex/config.toml`, `.codex/agents/*.toml`, and repo skills under
+`.agents/skills/` from the existing Claude Code assets.
+
+Literature search uses two external MCPs. arXiv is launched through
+`uv tool run arxiv-mcp-server==0.5.0`; OpenAlex is launched through
+`npx -y openalex-research-mcp@0.5.0`, so install Node.js/npm if you want the
+OpenAlex-backed librarian tools.
+
+<details><summary>Manual setup (without the wizard)</summary>
+
+```powershell
+uv sync --extra proof    # pulls in sentence-transformers for the proof trunk
+uv run python scripts/seed_proof_corpus.py
+uv run python scripts/seed_proof_failures.py
+```
+
+</details>
+
+For checkout development, open two terminals from the repo root:
+
+```powershell
+# Terminal A: Claude Code (from the repo root)
+claude
+
+# Or Terminal A: Codex (after choosing codex/both in setup)
+codex -C .
+
+# Terminal B: cockpit TUI (from the repo root)
+uv run python -m cockpit.tui
+```
+
+For the Chinese UI on Windows Terminal:
+
+```powershell
+chcp 65001
+$env:PYTHONUTF8=1
+uv run python -m cockpit.tui --lang zh
+```
+
+Press `L` inside the TUI to toggle English / Chinese labels.
+
+In Codex, start ClaudeScientist skills with `/skills` or `$skill-name`.
+Example:
+
+```text
+$research-sop investigate whether per-head dropout helps ViT scaling
+```
+
+In Codex, do not type `/research-sop`; that form is for Claude Code.
+If `$research-sop` does not appear in project-local development mode, check that
+`.agents/skills/research-sop/SKILL.md` exists and restart Codex. Installed plugin
+skills work from any project directory.
+
+Lean formal verification is a separate opt-in setup. In Codex, the generated
+Lean MCP server is disabled until you finish that setup. See
+[`docs/setup-lean.md`](docs/setup-lean.md).
+
+## Where to go next
+
+If you're new, read in this order:
+
+1. **[`docs/overview.md`](docs/overview.md)** — the complete mental model: how the pieces fit, what happens end-to-end, the three design principles
+2. **[`docs/workflows/first-research-task.md`](docs/workflows/first-research-task.md)** — walk through one full task from start to finish
+3. **[`docs/architecture.md`](docs/architecture.md)** — the contracts between modules (treat as binding)
+4. **[`docs/tool-reference.md`](docs/tool-reference.md)** — every MCP tool, with signature and usage guidance
+5. **[`docs/setup-codex-plugin.md`](docs/setup-codex-plugin.md)** — portable Codex installation and Cockpit trust checks
+
+More:
+
+- Design rationale for each major decision → [`docs/adr/`](docs/adr/)
+- Where the project is headed → [`docs/roadmap.md`](docs/roadmap.md)
+- Historical plans → [`docs/archive/`](docs/archive/)
+- Agent and contributor rules → [`AGENTS.md`](AGENTS.md)
+
+## Runtime details
+
+Default paths:
+
+- Shared state: `.research-agent/state.db` under the active research workspace
+- Generated reports: `reports/` under the active research workspace; gitignored by default,
+  force-add individual files only when you intentionally want to share them
+- Held-out datasets: `%USERPROFILE%\.research-agent\heldout`, configurable via `RESEARCH_AGENT_HELDOUT_DIR`
+- Embedding backend: `local` (sentence-transformers/Qwen/Qwen3-Embedding-0.6B); override with `RESEARCH_AGENT_EMBED_BACKEND=mock|openai`. Tests use `mock` automatically.
+
+Dev server commands for individual MCP modules:
+
+```powershell
+uv run python -m memory_mcp.dev_server
+uv run python -m verify_mcp.dev_server
+uv run python -m prove_mcp.dev_server
+uv run python -m cockpit.mcp_server
+uv run python -m claudescientist.heldout register <name> <path>
+```
+
+## Validation
+
+Before shipping a change:
+
+```powershell
+uv run ruff check
+uv run pytest tests/memory_mcp tests/verify_mcp tests/prove_mcp tests/hooks tests/cockpit tests/scripts tests/e2e
+uv run python -m cockpit.tui --once --lang zh
+uv run python -c "import memory_mcp.server; import verify_mcp.server; import prove_mcp.server; import cockpit.mcp_server; print('OK')"
+```
+
+## Current status
+
+The repo works for local development and integration. A fresh end-to-end validation pass is needed before calling it production-ready.
+
+A few things to know:
+
+- **Auto-prune is dry-run by default.** Set `RESEARCH_AGENT_AUTO_PRUNE=1` to let it actually pause weak branches.
+- **The cockpit is terminal-only.** No browser frontend, no web server.
+- **The prover agent works without Lean.** The NL proof workflow runs on its own; Lean is extra insurance you can set up later via [`docs/setup-lean.md`](docs/setup-lean.md).
+- **`mem_nodes.elo_score` is a legacy column.** New code should read `mem_bt_ratings.strength`.
+
+Protection labels are deliberately explicit: `enforced` means code blocks the
+normal operation; `agent_gated` means the agent workflow refuses or reviews it
+but is not a security boundary; `advisory` means warning only. Run
+`claudescientist doctor --workspace .` to see whether Cockpit intervention hooks
+are trusted or the current session has degraded to monitor-only mode.
+
+Full tool list and scope details: [`docs/tool-reference.md`](docs/tool-reference.md) and [`AGENTS.md`](AGENTS.md).

claudescientist-5.1.0/README.md

@@ -0,0 +1,228 @@
+# ClaudeScientist
+
+**A research co-pilot that remembers, verifies, and lets you steer.**
+
+[![version](https://img.shields.io/badge/version-v5.1.0-blue)](https://github.com/whenpoem/aiscientist/releases) [![python](https://img.shields.io/badge/python-%E2%89%A53.11-3776AB?logo=python&logoColor=white)](https://www.python.org/) [![CI](https://github.com/whenpoem/aiscientist/actions/workflows/ci.yml/badge.svg)](https://github.com/whenpoem/aiscientist/actions/workflows/ci.yml) [![license](https://img.shields.io/badge/license-MIT-yellow)](LICENSE)
+
+> 中文版本: [README.zh-CN.md](README.zh-CN.md)
+
+ClaudeScientist plugs into Claude Code or Codex and adds what most AI scientist systems leave out: it remembers what you've tried, verifies your numbers before you publish them, and gives you a live terminal dashboard where you can watch the research unfold and step in at any time.
+
+You give the agent a research question. It generates hypotheses, ranks them in a tournament, runs experiments with built-in safety checks, and tracks provenance for every number it produces. You watch the whole process in a second terminal and can reject, redirect, or approve at any point.
+
+**Current version**: v5.1.0 is a trust-calibration and portability release.
+Bradley-Terry rankings are refit from the complete ledger and no longer depend
+on comparison order; their intervals are honestly labelled as uncalibrated
+approximations. Bonferroni families are fixed when locked. Every central run
+automatically fingerprints code, inputs, Git state, dependencies, seeds, and
+runtime. A public Codex plugin bundles the core MCPs, Skills, hooks, and local
+Cockpit without tying them to this repository's working directory. The v5.0
+activity-streaming Cockpit remains intact; see
+[ADR 0011](docs/adr/0011-cockpit-activity-streaming.md).
+
+**v4.2.0 features retained** (see [retrospective-v4.2.md](docs/retrospective-v4.2.md)): tab grouping into Cross / Empirical / Proof, collapsible detail sections, pane-scoped `w`/`i`/`t` keys, the multi-provider vector backend (DashScope / Jina / Voyage / GLM tested via [ADR 0010](docs/adr/0010-multi-provider-embeddings.md), default local `Qwen/Qwen3-Embedding-0.6B`), reports-as-files (closure / draft / diagnostic / portfolio / cascade) per [ADR 0009](docs/adr/0009-reports-as-files-monitoring-as-tui.md), and the cold-start Welcome screen. See [architecture.md §13](docs/architecture.md#13-core-vs-domain-trunks-v40) for the two-trunk split.
+
+## What it looks like
+
+Open two terminals side by side. That's the whole UI.
+
+<picture>
+  <img alt="Cockpit TUI screenshot" src="docs/assets/image2.png" width="800">
+</picture>
+
+*The cockpit TUI — hypothesis tree, evidence, ratings, and event stream in one terminal.*
+
+The two terminals don't talk to each other directly — they both read and write the same SQLite file. This is the central design choice: every module collaborates through a shared database, not over the network.
+
+| Role | Where | What it does |
+|---|---|---|
+| **Claude Code / Codex** | Terminal A | Drives the research: understands your question, calls tools, writes and runs code |
+| **MCP servers** | Background | Provide the tools the agent calls — memory, verification, literature search, proof generation |
+| **Hooks** | Auto-loaded at startup | Run safety checks before/after every tool call (block data leaks, log provenance) |
+| **Cockpit TUI** | Terminal B | Shows live state; lets you approve, reject, or redirect hypotheses |
+| **SQLite** | `.research-agent/state.db` | The single file that holds all state: hypotheses, evidence, ratings, metrics, events |
+
+## What you can do with it
+
+- **Track your research thinking.** Every hypothesis, piece of evidence, and branching decision lives in a persistent graph. Papers you read along the way are compressed and searchable. Come back next week — it's all there. Want to revisit a direction you pruned? Run a counterfactual replay without touching the live state.
+- **Rank competing ideas.** A Bradley-Terry tournament compares hypotheses
+  head-to-head and produces an order-invariant leaderboard with explicitly
+  uncalibrated approximate posterior intervals. Use it with comparison coverage
+  and domain evidence, not as a significance test.
+- **Lock your goalposts before experimenting.** Preregistration makes you commit to a metric, direction, and threshold before you see results. Multiple-comparison correction is applied automatically.
+- **Make your numbers trustworthy.** Every reported number gets checked: Is it reproducible across random seeds? Which files produced it? Has anything changed since? Baseline comparisons are checked for fair compute budgets. A reviewer agent blocks any unverified claim from reaching a writeup.
+- **Catch mistakes before they compound.** A failure ledger remembers every debugging session. Next time you hit a similar problem, the system surfaces how you fixed it before.
+- **Watch and steer in real time.** The cockpit TUI shows the hypothesis tree, ratings, and event stream live. Press a key to reject a bad hypothesis or inject a note — interventions are picked up at the next turn.
+- **Generate and verify statistical proofs** *(v4.0).* A proof trunk handles drafting, segmentation, diagnosis against known error patterns, and optional Lean 4 formal verification.
+
+## Quick start
+
+### Install the public Codex plugin
+
+The plugin works from any research project; Codex does not need to start inside
+the ClaudeScientist source checkout.
+
+```powershell
+uv tool run --from claudescientist==5.1.0 claudescientist setup --scope user
+```
+
+This command installs the marketplace at the matching `v5.1.0` Git tag and
+then installs the plugin. The Python package and Git tag must both be published
+before this public command can work; source-checkout testing does not replace
+that release step. See [docs/setup-codex-plugin.md](docs/setup-codex-plugin.md)
+for the equivalent manual commands.
+
+Start a new Codex task after installation. Approve/trust the plugin hooks when
+Codex asks. MCP monitoring works without hook trust, but Cockpit interventions
+remain **monitor-only** until the hooks are trusted.
+
+From the research project you want to monitor:
+
+```powershell
+uv tool run --from claudescientist==5.1.0 claudescientist doctor --workspace .
+uv tool run --from claudescientist==5.1.0 claudescientist cockpit --workspace . --lang zh
+```
+
+Each project keeps independent state in its own `.research-agent/state.db`.
+The public plugin enables only the four local core MCPs (`memory`, `verify`,
+`prove`, `cockpit`). arXiv, OpenAlex, and Lean remain explicit opt-ins.
+
+### Develop from this checkout
+
+Install and run the setup wizard:
+
+```powershell
+uv sync
+uv run python -m claudescientist.setup
+```
+
+The wizard walks you through AI client selection (`claude`, `codex`, or
+`both`), embedding backend, proof corpus seeding, held-out directory, Lean
+toolchain, and auto-prune — all in one pass. Run it again any time; it skips
+steps that are already done.
+
+For non-interactive setup, set `CLAUDESCIENTIST_SETUP_AGENT_HOST=codex` or
+`CLAUDESCIENTIST_SETUP_AGENT_HOST=both`. Codex support is project-local: setup
+generates `.codex/config.toml`, `.codex/agents/*.toml`, and repo skills under
+`.agents/skills/` from the existing Claude Code assets.
+
+Literature search uses two external MCPs. arXiv is launched through
+`uv tool run arxiv-mcp-server==0.5.0`; OpenAlex is launched through
+`npx -y openalex-research-mcp@0.5.0`, so install Node.js/npm if you want the
+OpenAlex-backed librarian tools.
+
+<details><summary>Manual setup (without the wizard)</summary>
+
+```powershell
+uv sync --extra proof    # pulls in sentence-transformers for the proof trunk
+uv run python scripts/seed_proof_corpus.py
+uv run python scripts/seed_proof_failures.py
+```
+
+</details>
+
+For checkout development, open two terminals from the repo root:
+
+```powershell
+# Terminal A: Claude Code (from the repo root)
+claude
+
+# Or Terminal A: Codex (after choosing codex/both in setup)
+codex -C .
+
+# Terminal B: cockpit TUI (from the repo root)
+uv run python -m cockpit.tui
+```
+
+For the Chinese UI on Windows Terminal:
+
+```powershell
+chcp 65001
+$env:PYTHONUTF8=1
+uv run python -m cockpit.tui --lang zh
+```
+
+Press `L` inside the TUI to toggle English / Chinese labels.
+
+In Codex, start ClaudeScientist skills with `/skills` or `$skill-name`.
+Example:
+
+```text
+$research-sop investigate whether per-head dropout helps ViT scaling
+```
+
+In Codex, do not type `/research-sop`; that form is for Claude Code.
+If `$research-sop` does not appear in project-local development mode, check that
+`.agents/skills/research-sop/SKILL.md` exists and restart Codex. Installed plugin
+skills work from any project directory.
+
+Lean formal verification is a separate opt-in setup. In Codex, the generated
+Lean MCP server is disabled until you finish that setup. See
+[`docs/setup-lean.md`](docs/setup-lean.md).
+
+## Where to go next
+
+If you're new, read in this order:
+
+1. **[`docs/overview.md`](docs/overview.md)** — the complete mental model: how the pieces fit, what happens end-to-end, the three design principles
+2. **[`docs/workflows/first-research-task.md`](docs/workflows/first-research-task.md)** — walk through one full task from start to finish
+3. **[`docs/architecture.md`](docs/architecture.md)** — the contracts between modules (treat as binding)
+4. **[`docs/tool-reference.md`](docs/tool-reference.md)** — every MCP tool, with signature and usage guidance
+5. **[`docs/setup-codex-plugin.md`](docs/setup-codex-plugin.md)** — portable Codex installation and Cockpit trust checks
+
+More:
+
+- Design rationale for each major decision → [`docs/adr/`](docs/adr/)
+- Where the project is headed → [`docs/roadmap.md`](docs/roadmap.md)
+- Historical plans → [`docs/archive/`](docs/archive/)
+- Agent and contributor rules → [`AGENTS.md`](AGENTS.md)
+
+## Runtime details
+
+Default paths:
+
+- Shared state: `.research-agent/state.db` under the active research workspace
+- Generated reports: `reports/` under the active research workspace; gitignored by default,
+  force-add individual files only when you intentionally want to share them
+- Held-out datasets: `%USERPROFILE%\.research-agent\heldout`, configurable via `RESEARCH_AGENT_HELDOUT_DIR`
+- Embedding backend: `local` (sentence-transformers/Qwen/Qwen3-Embedding-0.6B); override with `RESEARCH_AGENT_EMBED_BACKEND=mock|openai`. Tests use `mock` automatically.
+
+Dev server commands for individual MCP modules:
+
+```powershell
+uv run python -m memory_mcp.dev_server
+uv run python -m verify_mcp.dev_server
+uv run python -m prove_mcp.dev_server
+uv run python -m cockpit.mcp_server
+uv run python -m claudescientist.heldout register <name> <path>
+```
+
+## Validation
+
+Before shipping a change:
+
+```powershell
+uv run ruff check
+uv run pytest tests/memory_mcp tests/verify_mcp tests/prove_mcp tests/hooks tests/cockpit tests/scripts tests/e2e
+uv run python -m cockpit.tui --once --lang zh
+uv run python -c "import memory_mcp.server; import verify_mcp.server; import prove_mcp.server; import cockpit.mcp_server; print('OK')"
+```
+
+## Current status
+
+The repo works for local development and integration. A fresh end-to-end validation pass is needed before calling it production-ready.
+
+A few things to know:
+
+- **Auto-prune is dry-run by default.** Set `RESEARCH_AGENT_AUTO_PRUNE=1` to let it actually pause weak branches.
+- **The cockpit is terminal-only.** No browser frontend, no web server.
+- **The prover agent works without Lean.** The NL proof workflow runs on its own; Lean is extra insurance you can set up later via [`docs/setup-lean.md`](docs/setup-lean.md).
+- **`mem_nodes.elo_score` is a legacy column.** New code should read `mem_bt_ratings.strength`.
+
+Protection labels are deliberately explicit: `enforced` means code blocks the
+normal operation; `agent_gated` means the agent workflow refuses or reviews it
+but is not a security boundary; `advisory` means warning only. Run
+`claudescientist doctor --workspace .` to see whether Cockpit intervention hooks
+are trusted or the current session has degraded to monitor-only mode.
+
+Full tool list and scope details: [`docs/tool-reference.md`](docs/tool-reference.md) and [`AGENTS.md`](AGENTS.md).

claudescientist-5.1.0/pyproject.toml

@@ -0,0 +1,92 @@
+[project]
+name = "claudescientist"
+version = "5.1.0"
+description = "Research-agent augmentation layer for Claude Code with SQLite memory, verification MCPs, a proof trunk with NL workflow + Lean reinsurance, and a Textual cockpit TUI."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "whenpoem" },
+]
+keywords = [
+    "claude-code",
+    "mcp",
+    "research",
+    "sqlite",
+    "textual",
+    "tui",
+    "proof",
+    "lean",
+    "statistics",
+    "formal-methods",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Mathematics",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+dependencies = [
+    "fastmcp>=3.2.4",
+    "numpy>=1.26",
+    "pydantic>=2.13.1",
+    "textual>=8.2,<9.0",
+    # questionary drives the interactive `python -m claudescientist.setup`
+    # wizard. ~30KB itself; pulls in prompt-toolkit (~450KB) which is a
+    # widely-shipped dep. Listed as a main requirement (rather than an
+    # extra) so first-run users can hit setup without an extra install
+    # step. Setup's --non-interactive path does NOT touch questionary.
+    "questionary>=2.0",
+]
+
+[project.scripts]
+claudescientist = "claudescientist.cli:main"
+
+[project.optional-dependencies]
+# Live embedding backends for the proof trunk (`prove_mcp`). Tests stay on the
+# deterministic mock backend (see tests/conftest.py); these extras are for
+# real cold-start ingest of the proof corpus + diagnose_snippet retrievals.
+embed-local  = ["sentence-transformers>=2.2"]
+embed-openai = ["openai>=1.0"]
+proof        = ["sentence-transformers>=2.2"]   # alias: recommended local setup
+all          = ["sentence-transformers>=2.2", "openai>=1.0"]
+
+[project.urls]
+Repository = "https://github.com/whenpoem/aiscientist"
+Issues = "https://github.com/whenpoem/aiscientist/issues"
+
+[build-system]
+requires = ["uv_build>=0.11.7,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-name = [
+    "claudescientist",
+    "cockpit",
+    "memory_mcp",
+    "prove_mcp",
+    "verify_mcp",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.3",
+    "pytest-asyncio>=1.3.0",
+    "ruff>=0.15.10",
+]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-ra"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests", ".claude/hooks"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]

claudescientist-5.1.0/src/claudescientist/__init__.py

@@ -0,0 +1,68 @@
+"""claudescientist - Foundation runtime layer for ClaudeScientist.
+
+Owns project-wide path resolution, the SQLite connection helper, schema
+migration bookkeeping, the cockpit-event emit primitive, the project-level
+metric-recognition regexes, and the component bootstrap registry. Every
+business module (memory_mcp, verify_mcp, cockpit) depends on this; this
+module must not depend on any of them.
+
+Public surface
+--------------
+runtime.state_db_path()           Resolve the shared SQLite file path.
+runtime.heldout_root()            Resolve the sequestered-dataset root.
+runtime.connect_sqlite()          WAL-mode connection with row factory.
+runtime.connect_existing_sqlite() Hook-safe existing-DB connection helper.
+runtime.apply_schema_migration()  Per-component schema apply + bookkeeping.
+runtime.emit_cockpit_event()      Append a row to cockpit_events in-tx.
+runtime.METRIC_RE / NUMBER_RE     Project-wide numeric-claim recognition.
+runtime.extract_metric_tokens()   Pull labelled metric values from text.
+runtime.bootstrap_all()           Bootstrap every registered component.
+heldout.compute_manifest()        Hash a directory into a content manifest.
+heldout.load_manifest()           Read a previously-written manifest.
+heldout.write_manifest()          Persist a manifest next to the dataset.
+heldout.dataset_root()            Resolve a named dataset's root path.
+heldout.main()                    CLI entry point (lazy bridge to verify_mcp).
+
+Owned tables
+------------
+ra_migrations         Per-component schema version + apply status (created
+                      on demand by apply_schema_migration).
+cockpit_events        Append-only event stream (created on demand by
+                      emit_cockpit_event); cross-module signals go here.
+
+Critical invariants
+-------------------
+- runtime never imports memory_mcp, verify_mcp, or cockpit at module level.
+  ``bootstrap_all`` uses ``importlib.import_module`` so this stays true.
+- ``state_db_path()`` is the only legitimate way to find the SQLite file.
+  Do not duplicate path resolution.
+- ``METRIC_RE`` / ``extract_metric_tokens`` are project-wide; verify_mcp.
+  provenance and the hooks both consume them through this module.
+- ``KNOWN_BOOTSTRAP_COMPONENTS`` is the single registry of "modules that
+  own a SQLite schema". Add new MCP servers here, not in cockpit.
+
+Where things live
+-----------------
+Path / DB helpers:        runtime.py
+Schema migration:         runtime.apply_schema_migration
+Numeric recognition:      runtime.METRIC_RE, NUMBER_RE, extract_metric_tokens
+Component bootstrap:      runtime.KNOWN_BOOTSTRAP_COMPONENTS, bootstrap_all
+Pure file ops:            heldout.py (compute_manifest etc.)
+CLI entry shim:           heldout.main -> verify_mcp.heldout_cli.main
+
+Do NOT
+------
+- Import from memory_mcp, verify_mcp, or cockpit at module level. The CLI
+  forwarder in heldout.main does the import lazily; that is the only
+  permitted exception.
+- Add SQL DDL to runtime.py for business tables. Each component owns its
+  own schema in its own db.py.
+- Hard-code paths into the project tree. Always go through state_db_path,
+  heldout_root, or runtime_path.
+"""
+
+from __future__ import annotations
+
+__all__ = ["__version__"]
+
+__version__ = "5.1.0"