ai-crucible 0.2.0__tar.gz

ai_crucible-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,79 @@
+name: CI
+
+# Paths-gated so CI minutes only burn on changes that can affect the build
+# (per .claude/rules/github-actions.md — non-negotiable). pull_request covers
+# branch validation; workflow_dispatch is the manual fallback.
+on:
+  push:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+  pull_request:
+    paths:
+      - "src/**"
+      - "tests/**"
+      - "pyproject.toml"
+      - ".github/workflows/**"
+  workflow_dispatch:
+
+# Cancel superseded runs on the same ref (required by github-actions rules).
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # The two most-tested floors. 3.11 is the supported lower bound
+        # (requires-python >=3.11) and 3.12 is the upper end exercised here.
+        python-version: ["3.11", "3.12"]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Sync dependencies (dev + stats extras)
+        run: uv sync --extra dev --extra stats --python ${{ matrix.python-version }}
+
+      - name: Lint (ruff)
+        run: uv run ruff check .
+
+      - name: Read coverage floor from pyproject
+        id: covfloor
+        shell: bash
+        run: |
+          # Single source of truth: pyproject [tool.coverage.report].fail_under.
+          # Keeping the gate here in lockstep with pyproject avoids drift.
+          floor=$(uv run python -c "import tomllib,pathlib; print(tomllib.loads(pathlib.Path('pyproject.toml').read_text())['tool']['coverage']['report']['fail_under'])")
+          echo "floor=$floor" >> "$GITHUB_OUTPUT"
+          echo "Coverage floor: $floor%"
+
+      - name: Test (pytest + coverage gate)
+        run: >-
+          uv run pytest
+          --cov=ai_crucible
+          --cov-report=term-missing
+          --cov-fail-under=${{ steps.covfloor.outputs.floor }}
+
+      - name: Dependency audit (pip-audit on runtime deps)
+        run: |
+          # Ship Gate D: ecosystem-appropriate dependency scanning. Audit the
+          # resolved RUNTIME deps from the lockfile (not dev/stats tooling).
+          uv export --format requirements-txt --no-emit-project --no-hashes > requirements-audit.txt
+          uvx pip-audit -r requirements-audit.txt

ai_crucible-0.2.0/.github/workflows/pages.yml

@@ -0,0 +1,50 @@
+name: Deploy site to GitHub Pages
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'site/**'
+      - '.github/workflows/pages.yml'
+  workflow_dispatch:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+
+      - name: Install site dependencies
+        working-directory: site
+        run: npm ci
+
+      - name: Build site
+        working-directory: site
+        run: npm run build
+
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site/dist
+
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4

ai_crucible-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,190 @@
+name: Release
+
+# On a published GitHub Release this:
+#   1. publishes the Python package to PyPI via Trusted Publishing (OIDC, no token),
+#   2. builds PyInstaller binaries for each platform + uploads them (+ checksums) to the release,
+#   3. publishes the @dogfood-lab/ai-crucible npm wrapper (the npm-launcher) via Trusted Publishing.
+#
+# Org rules (.claude/rules/github-actions.md): publish workflows fire on `release: published` only.
+# The repo has ci.yml + this release.yml (the org CI/publish pair) plus pages.yml — pages.yml is the
+# accepted GitHub-Pages-deploy exception (paths-gated to site/**), and the cross-OS binary matrix is
+# the explicit-request exception to the "1 OS / no macos" rule, because the npm launcher distributes
+# platform binaries.
+#
+# First-publish prerequisites (one-time, on the registries):
+#   * PyPI: a pending publisher for project `ai-crucible`, workflow `release.yml` — ALREADY SET
+#     (repository dogfood-lab/ai-crucible, environment "(Any)").
+#   * npm: a v0.0.0 placeholder publish of @dogfood-lab/ai-crucible (reserves the name) + a Trusted
+#     Publisher on npmjs.com (workflow release.yml, org dogfood-lab, repo ai-crucible).
+#   * Do NOT enable "require 2FA / disallow tokens" on the npm package until after the first CI publish.
+#
+# NOTE: the PyInstaller step bundles inspect-ai + the scientific stack; the first CI run may need a
+# hidden-import/collect tweak (a known PyInstaller reality). A failure there is contained — the PyPI
+# job is independent and still publishes; re-dispatch fixes binaries + the npm wrapper.
+
+on:
+  release:
+    types: [published]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: false # never cancel an in-flight publish
+
+jobs:
+  pypi:
+    name: Publish to PyPI (Trusted Publishing)
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # OIDC handshake for PyPI Trusted Publishing — the only auth needed
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Verify the tag matches pyproject version
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(grep -m1 '^version = ' pyproject.toml | sed -E 's/version = "(.*)"/\1/')
+          echo "tag=${TAG} pyproject=${PKG}"
+          if [ "${TAG}" != "${PKG}" ]; then
+            echo "::error::release tag ${TAG} does not match pyproject version ${PKG}"
+            exit 1
+          fi
+
+      - uses: astral-sh/setup-uv@v6
+
+      - name: Build sdist + wheel
+        run: uv build
+
+      - name: Check distribution metadata
+        run: uvx twine check dist/*
+
+      - name: Publish to PyPI
+        # Trusted Publishing: no token. PEP 740 attestations are on by default (action >= v1.11.0).
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  build-binaries:
+    name: Build PyInstaller binary (${{ matrix.target }})
+    strategy:
+      fail-fast: false # one OS's failure must not cancel the others
+      matrix:
+        include:
+          - os: ubuntu-latest
+            target: linux-x64
+            ext: ""
+          - os: macos-latest
+            target: darwin-arm64
+            ext: ""
+          # darwin-x64 omitted: macos-13 is deprecated; the arm64 binary runs via Rosetta.
+          - os: windows-latest
+            target: win-x64
+            ext: ".exe"
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 25
+    steps:
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v6
+      - run: uv python install 3.12
+      - run: uv venv
+
+      - name: Install ai-crucible + PyInstaller
+        # The [stats] extra pulls statsmodels (the κ machinery the characterize path uses); the
+        # core deps (inspect-ai, numpy, scipy, pydantic) come with the project install.
+        run: uv pip install ".[stats]" "pyinstaller>=6.9.0"
+
+      - name: Build binary
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          uv run pyinstaller --onefile --name ai-crucible --console \
+            --collect-submodules ai_crucible \
+            --collect-all inspect_ai \
+            --collect-submodules pydantic \
+            --collect-submodules scipy \
+            --collect-submodules statsmodels \
+            --collect-submodules numpy \
+            --copy-metadata ai-crucible \
+            src/ai_crucible/__main__.py
+          OUTNAME="ai-crucible-${VERSION}-${{ matrix.target }}${{ matrix.ext }}"
+          mv "dist/ai-crucible${{ matrix.ext }}" "dist/${OUTNAME}"
+          echo "ASSET_NAME=${OUTNAME}" >> "$GITHUB_ENV"
+
+      - name: Smoke-test the binary
+        shell: bash
+        run: dist/${{ env.ASSET_NAME }} --version
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: binary-${{ matrix.target }}
+          path: dist/${{ env.ASSET_NAME }}
+
+  release-binaries:
+    name: Upload binaries + checksums to the release
+    needs: build-binaries
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write # upload assets to the release
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+          merge-multiple: true
+
+      - name: Generate checksums
+        shell: bash
+        run: |
+          VERSION=${GITHUB_REF_NAME#v}
+          cd artifacts
+          sha256sum * > "checksums-${VERSION}.txt"
+          cat "checksums-${VERSION}.txt"
+
+      - uses: softprops/action-gh-release@v2
+        with:
+          files: artifacts/*
+
+  npm:
+    name: Publish npm wrapper (Trusted Publishing)
+    needs: release-binaries # the wrapper is only useful once the binaries are on the release
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write # npm provenance via Sigstore OIDC
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Verify the npm wrapper version matches the tag
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(node -p "require('./npm/package.json').version")
+          echo "tag=${TAG} npm=${PKG}"
+          if [ "${TAG}" != "${PKG}" ]; then
+            echo "::error::release tag ${TAG} does not match npm/package.json version ${PKG}"
+            exit 1
+          fi
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+          registry-url: "https://registry.npmjs.org"
+
+      - name: Install npm >= 11.5 for OIDC trusted-publishing auth
+        run: |
+          # Node 22's bundled npm 10.9 races on an in-place `npm install -g npm@latest`
+          # (MODULE_NOT_FOUND: promise-retry). Install npm@latest into a sandbox and shadow it.
+          SANDBOX="$HOME/.npm-cli-sandbox"
+          mkdir -p "$SANDBOX"
+          pushd "$SANDBOX" >/dev/null
+          echo '{"name":"npm-cli-sandbox","version":"0.0.0","private":true}' > package.json
+          npm install --no-save --no-audit --no-fund --silent npm@latest
+          popd >/dev/null
+          echo "$SANDBOX/node_modules/.bin" >> "$GITHUB_PATH"
+          "$SANDBOX/node_modules/.bin/npm" --version
+
+      - name: Publish wrapper with provenance (OIDC trusted publisher)
+        working-directory: npm
+        run: |
+          npm install --no-save --no-audit --no-fund
+          npm publish --provenance --access public

ai_crucible-0.2.0/.gitignore

@@ -0,0 +1,57 @@
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Editors
+.vscode/
+.idea/
+*.swp
+*~
+
+# Env / secrets
+.env
+.env.*
+!.env.example
+*.key
+*.pem
+
+# Dependencies
+node_modules/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+
+# Build artifacts
+dist/
+build/
+*.tsbuildinfo
+
+# Python tooling caches
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Logs
+*.log
+npm-debug.log*
+
+# Local scratch
+scratch/
+tmp/
+
+# Polyglot translation cache
+.polyglot-cache.json
+
+# pip-audit scratch
+requirements-audit.txt
+
+# characterization run outputs
+char-*.json
+characterization-report.json
+site/.astro/

ai_crucible-0.2.0/CHANGELOG.md

@@ -0,0 +1,48 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+## [Unreleased]
+
+## [0.2.0] - 2026-06-01
+
+Phase-1 milestone: the policy-enforced kernel + role contracts + instrument-quality
+scaffolding, built greenfield from a citation-verified design lock. Pre-1.0 by
+design — this is Phase 1 of a multi-phase research instrument (see Notes).
+
+### Added
+- **Phase-1 kernel** — a thin policy layer on [Inspect AI](https://inspect.aisi.org.uk/),
+  nine modules threaded through one observable `generate` choke point:
+  `puzzle_loader`, `sandbox`, `roles`, `budget_governor`, `oracle_scorer`,
+  `judge_panel`, `trace_writer`, `observability`, `attestation`. Entry points
+  `run_attempt` / `run_pass_hat_k`.
+- **Layered Reward Surface + Sealed Boundary** — prompt-framing as a first-class
+  measured arm (`neutral` / `self_referential` / `social_standings`); the
+  motivating surface (chrome) never shares a context window with the scored,
+  out-of-band-graded surface.
+- **Scoring** — `pass^k`, Wilson / Clopper-Pearson intervals, McNemar, the
+  graduation rule, the §8.3 conjunctive hard gate, and a cross-family judge panel
+  that excludes the generator's family (external verifier).
+- **Instrument-quality scaffolding** — AsPredicted + REFORMS pre-registration
+  templates, content-hashed rubric bundle with version-bump, Sobol screen +
+  deterministic split + Thresholdout budget, `SUT.yaml`, and Inspect-AI task
+  mapping (the §9 audit chain).
+- **First seed puzzle** — `puzzles/seed-sulzbach-55252/` (claude-code#55252:
+  fabrication / looping-on-diagnosis) with a grading-side oracle + fingerprinted
+  bait honeypot.
+- **Design lock** — `docs/research-grounding.md` §10, grounded in two
+  citation-verified study-swarms (`docs/phase-0/swarm-16..25`; every arXiv ID
+  verified, corrections recorded inline).
+- **Shipping baseline** — CI (ruff + pytest + 60% coverage gate on Python
+  3.11/3.12 + dependency audit), `SECURITY.md` threat model, MIT `LICENSE`, and a
+  `verify.sh` one-command gate.
+
+### Notes
+- **Pre-1.0 research instrument.** Phase 1 of a multi-phase build. The real
+  cross-family local-model panel (Phase 2), the hardened container/microVM sandbox
+  provider, and the cosign/Rekor external attestation anchor are deferred to
+  Phase 2+ and are documented as such. No package has been published.
+- `0.1.0` was an internal scaffold version, never tagged or released.

ai_crucible-0.2.0/LICENSE

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

ai_crucible-0.2.0/PKG-INFO

@@ -0,0 +1,125 @@
+Metadata-Version: 2.4
+Name: ai-crucible
+Version: 0.2.0
+Summary: Diagnostic adversarial game for frontier LLMs — a policy-enforced kernel that mediates a Designer/Solver/Judge cycle, scores against a hidden oracle, and curates a Lab/Arena/Regression catalog.
+Project-URL: Homepage, https://github.com/dogfood-lab/ai-crucible
+Project-URL: Repository, https://github.com/dogfood-lab/ai-crucible
+Author-email: mcp-tool-shop <64996768+mcp-tool-shop@users.noreply.github.com>
+License: MIT
+License-File: LICENSE
+Keywords: auditing-game,diagnostic,evaluation,inspect-ai,llm,reward-hacking
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: <3.14,>=3.11
+Requires-Dist: inspect-ai>=0.3
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic>=2.5
+Requires-Dist: scipy>=1.11
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest-cov>=5; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: stats
+Requires-Dist: statsmodels>=0.14; extra == 'stats'
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <a href="README.ja.md">日本語</a> | <a href="README.zh.md">中文</a> | <a href="README.es.md">Español</a> | <a href="README.fr.md">Français</a> | <a href="README.hi.md">हिन्दी</a> | <a href="README.it.md">Italiano</a> | <a href="README.pt-BR.md">Português (BR)</a>
+</p>
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/dogfood-lab/ai-crucible/main/assets/logo.png" alt="ai-crucible" width="500" />
+</p>
+
+<p align="center">
+  <a href="https://github.com/dogfood-lab/ai-crucible/actions/workflows/ci.yml"><img src="https://github.com/dogfood-lab/ai-crucible/actions/workflows/ci.yml/badge.svg" alt="CI" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT License" /></a>
+  <img src="https://img.shields.io/badge/python-3.11%E2%80%933.13-blue.svg" alt="Python 3.11–3.13" />
+  <img src="https://img.shields.io/badge/coverage-96%25-brightgreen.svg" alt="Coverage 96%" />
+  <a href="CHANGELOG.md"><img src="https://img.shields.io/badge/version-0.2.0-orange.svg" alt="Version 0.2.0" /></a>
+  <a href="https://dogfood-lab.github.io/ai-crucible/"><img src="https://img.shields.io/badge/docs-handbook-orange.svg" alt="Handbook" /></a>
+</p>
+
+<p align="center"><b>A diagnostic adversarial game for frontier LLMs — a measurement instrument that happens to be fun.</b></p>
+
+One Claude session (**Designer**) crafts puzzles targeting real, currently-observed capability gaps. Another (**Solver**) attempts them. A policy-enforced kernel mediates, scores against a hidden oracle, and curates a catalog through a `Lab → Arena → Regression` lifecycle. Puzzles are grounded in empirical signal — real GitHub issues, academic literature, observed failures in the field — not synthetic.
+
+## What makes it different
+
+- **Capability, not "cheating."** AI Crucible distinguishes *elegance* and *novelty* (rewarded) from *answer-bypass* (penalized). Lateral thinking is a capability to measure, not a vice to punish.
+- **The instrument measures itself.** Prompt framing is a first-class measured arm — the kernel runs the same puzzle under `neutral` / `self_referential` / `social_standings` framings and reports its own prompt-effect as a diagnostic.
+- **A sealed measurement boundary.** Motivation and measurement never share a context window; the hidden oracle is graded out-of-band by a different model family with the agent's reasoning hidden. The model can't game what it can't perceive.
+- **Reliability by consistency.** `pass^k` (all *k* independent trials succeed), Wilson intervals, and cross-family judge panels — built to report distributions, not point estimates.
+- **A living catalog.** Solved puzzles are *demoted* to `Regression`, never deleted, so the catalog becomes a capability-evolution timeline as the frontier moves.
+
+## Threat model (summary)
+
+AI Crucible's primary adversary is the **model under measurement**, which may try to reach the answer key or to detect and game the eval. It **touches**: puzzle prompts/setup, the Solver's own confined working directory, and the model-provider API calls the operator configures. It does **not** touch: the oracle/answer key (graded out-of-band on a separate host the Solver cannot reach) or motivation "chrome" (rank/standings — never injected into the scored context). **Permissions:** model-provider keys via environment variables at runtime; no bundled secrets, no telemetry, no outbound calls of its own. Full disclosure — including where a boundary is *defense-in-depth* rather than a hard guarantee — is in **[SECURITY.md](SECURITY.md)**.
+
+## Architecture
+
+AI Crucible is a **thin policy layer on [Inspect AI](https://inspect.aisi.org.uk/)** (UK AISI), not a from-scratch harness. A single `AttemptState` object is threaded Designer → Solver → (Critic) → Judge through **one `generate` choke point**, so every model and tool call is observable.
+
+| Module | Responsibility |
+| ------ | -------------- |
+| `puzzle_loader` | Loads a puzzle directory (`meta.json` / `prompt` / `setup_script`) into Solver-visible state. **Never touches the oracle.** |
+| `sandbox` | Narrow `exec` / `read_file` / `write_file` channel into a locked, network-less container. |
+| `roles` | The five role slots (Designer / Solver / Critic / Judge / CohortSolver). Only Solver gets tools; Critic is interface-reserved, default-off. |
+| `budget_governor` | Per-class tool-call + wall-clock budgets, displayed to the agent, enforced kernel-side; hard-kill on pathological loops. |
+| `oracle_scorer` | Out-of-band grading: solved-**and**-no-regression against the hidden oracle (SWE-bench pattern). |
+| `judge_panel` | Cross-family panel of model-scorers + reducer (PoLL) for novelty validation and bypass detection. |
+| `trace_writer` | Per-attempt transcript in the Inspect `EvalLog` shape; large blobs stored by digest. |
+| `observability` | Per-attempt → per-puzzle → per-model rollups; `pass^k` native. |
+| `attestation` | Cryptographic provenance (cosign + event-store) behind a typed subprocess boundary. |
+
+The sealed boundary runs in three tiers — **Tier 1** scored context (deployment-shaped, framing-neutral), **Tier 2** engagement framing (probed for contamination each release), **Tier 3** chrome (rank/leaderboard — human-facing UI only, never in a context the model solves in). The full design rationale, with citations, is in [`docs/research-grounding.md`](docs/research-grounding.md).
+
+## Install
+
+```bash
+# As a Python library + CLI (PyPI):
+pip install ai-crucible          # or: uv pip install ai-crucible
+ai-crucible --help
+
+# Or zero-prerequisite via npx — downloads a verified binary, no Python needed:
+npx @dogfood-lab/ai-crucible --help
+```
+
+> **Research preview (v0.2.x).** The judge panel's alt-test ω is still a *circular model-jury bootstrap* until a human-labeling round runs, so seated judges are **provisional** and the composed panel **escalates to a Claude Designer** below quorum. See the [scorecard](SCORECARD.md) for the honest, non-cosmetic gate results.
+
+## Quick start (from source)
+
+AI Crucible uses [`uv`](https://docs.astral.sh/uv/) for environment and dependency management. Python **3.11+**.
+
+```bash
+# Create the venv and install the dev + stats extras
+uv sync --extra dev --extra stats
+
+# Run the test suite (with the coverage gate)
+uv run pytest --cov=ai_crucible --cov-report=term-missing
+
+# Lint
+uv run ruff check .
+
+# One command: lint + tests + build + smoke
+bash verify.sh
+```
+
+## Documentation
+
+- **[Handbook](https://dogfood-lab.github.io/ai-crucible/)** — guides, architecture, and reference.
+- [`docs/research-grounding.md`](docs/research-grounding.md) — design rationale, with citations.
+- [`docs/gameplan.md`](docs/gameplan.md) — roadmap and open questions.
+- [`SECURITY.md`](SECURITY.md) — threat model + honest residual-risk disclosure.
+
+## License
+
+[MIT](LICENSE). Public and pre-1.0 — see the [CHANGELOG](CHANGELOG.md) for version status.
+
+---
+
+<p align="center"><sub>Built by <a href="https://mcp-tool-shop.github.io/">MCP Tool Shop</a> · part of the <a href="https://github.com/dogfood-lab">dogfood-lab</a> workshop for testing in the AI era.</sub></p>