agent-readiness 1.0.0__tar.gz

agent_readiness-1.0.0/.devcontainer/devcontainer.json

@@ -0,0 +1,5 @@
+{
+  "name": "agent-readiness",
+  "image": "mcr.microsoft.com/devcontainers/python:3.12",
+  "postCreateCommand": "pip install -e '.[dev]'"
+}

agent_readiness-1.0.0/.env.example

@@ -0,0 +1,2 @@
+# Add environment variables required by this project here.
+# Copy to .env and fill in values before running.

agent_readiness-1.0.0/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,17 @@
+---
+name: Bug report
+about: Report a bug in agent-readiness
+title: "[Bug] "
+labels: bug
+---
+
+**Describe the bug**
+
+**To reproduce**
+```
+PYTHONPATH=src python3 -m agent_readiness.cli scan <repo>
+```
+
+**Expected behavior**
+
+**Actual behavior**

agent_readiness-1.0.0/.github/dependabot.yml

@@ -0,0 +1,10 @@
+version: 2
+updates:
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"

agent_readiness-1.0.0/.github/pull_request_template.md

@@ -0,0 +1,5 @@
+## Summary
+
+## Test plan
+- [ ] `make lint && make test` passes
+- [ ] `PYTHONPATH=src python3 -m agent_readiness.cli scan .` score does not regress

agent_readiness-1.0.0/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+      - run: pip install -e ".[dev]"
+      - run: make lint
+      - run: make test
+      - run: python -m agent_readiness.cli scan . --json
+        env:
+          PYTHONPATH: src

agent_readiness-1.0.0/.github/workflows/release.yml

@@ -0,0 +1,99 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build
+        run: pip install build
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Verify dist contents
+        run: ls -lh dist/
+
+      - uses: actions/upload-artifact@v7
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/agent-readiness
+    permissions:
+      id-token: write   # Required for OIDC trusted publishing
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write   # Required to create releases and upload assets
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v3
+        with:
+          generate_release_notes: true
+          files: dist/*
+
+  publish-github-packages:
+    name: Publish to GitHub Packages
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      packages: write
+
+    steps:
+      - uses: actions/download-artifact@v8
+        with:
+          name: dist
+          path: dist/
+
+      - name: Install twine
+        run: pip install twine
+
+      - name: Publish to GitHub Packages
+        run: |
+          twine upload \
+            --repository-url https://upload.pkg.github.com/ \
+            --username ${{ github.actor }} \
+            --password ${{ secrets.GITHUB_TOKEN }} \
+            dist/*

agent_readiness-1.0.0/.gitignore

@@ -0,0 +1,12 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv/
+venv/
+.env
+.pytest_cache/
+.ruff_cache/
+dist/
+build/
+.coverage
+node_modules/

agent_readiness-1.0.0/.pre-commit-config.yaml

@@ -0,0 +1,14 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.6.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-added-large-files
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.4.4
+    hooks:
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format

agent_readiness-1.0.0/AGENTS.md

@@ -0,0 +1,65 @@
+# Agent guide
+
+Conventions for AI coding agents working in this repository.
+
+## Canonical commands
+
+- Install dev deps: `make dev`
+- Run tests:        `make test`
+- Lint:             `make lint`
+- Run the CLI:      `PYTHONPATH=src python3 -m agent_readiness.cli scan .`
+  (or `agent-readiness scan .` after `make install`)
+
+The tool itself is fully headless: stable JSON via `--json`, tab-separated
+`list-checks`, prose `explain <check_id>`, and exit codes that mean
+things. There are no required interactive prompts.
+
+## Source of truth
+
+- [`RUBRIC.md`](./RUBRIC.md) — what we benchmark and why. Every check
+  must justify itself against the pillars and the headless-first
+  principle here.
+- [`SANDBOX.md`](./SANDBOX.md) — Docker execution model for `--run`
+  (Phase 2). Devcontainer-first, hard fail on docker-native repos,
+  no host-execution fallback.
+- [`PLAN.md`](./PLAN.md) — phased roadmap.
+
+If a behaviour is in the code but not in these three docs, the docs are
+the bug.
+
+## Adding a check
+
+1. Create a module under `src/agent_readiness/checks/`.
+2. Define a function decorated with `@register(...)` returning a
+   `CheckResult`.
+3. Import the new module from `src/agent_readiness/checks/__init__.py`
+   inside `_ensure_loaded`.
+4. Update `RUBRIC.md` and `PLAN.md` so the check has a name-able line
+   to an agent failure mode (the discipline that keeps us out of
+   linter creep).
+5. Add or extend a fixture so the check actually fires; update
+   `tests/test_phase1.py` snapshots if expected scores shift.
+
+## Do-not-touch (without a clear reason)
+
+- Default pillar weights in `src/agent_readiness/scorer.py`.
+  Changing these moves every reported score; coordinate with a
+  rubric update.
+- The JSON `schema` integer in `models.Report`. Bump only on
+  intentional breaking changes; downstream consumers will pin.
+- `src/agent_readiness/sandbox.py` contracts (preflight, no host
+  fallback, two-phase execution). The hard rules live in SANDBOX.md.
+
+## Style
+
+- Stdlib + click + (optional) rich. No pydantic, no typer, no heavy
+  static-analysis libs in Phase 1 — those land per-phase as needed.
+- Type-annotated, `from __future__ import annotations` at the top of
+  modules.
+- Conservative regex/heuristic checks: false positives erode trust
+  faster than false negatives.
+
+## Branch + commit conventions
+
+- Feature branches: `feat/<short-description>`
+- Conventional Commits style for messages where reasonable.

agent_readiness-1.0.0/CHANGELOG.md

@@ -0,0 +1,149 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+Format: [Keep a Changelog](https://keepachangelog.com/en/1.1.0/)
+
+## [Unreleased]
+
+## [1.0.0] - 2026-04-28
+
+### Added
+- `scan` shows a per-check progress visualizer on stderr (rich when
+  available, plain `\r` fallback otherwise). Auto-disabled for `--json`
+  and non-TTY stderr; opt-out with `--no-progress`. Stdout contract
+  (report / JSON) is unchanged.
+- `ci.configured`: detect Earthly (`Earthfile`), Drone CI
+  (`.drone.yml` / `.drone.yaml`), and Woodpecker CI
+  (`.woodpecker.yml` / `.woodpecker.yaml` / `.woodpecker/`). Reported
+  by users running monorepos where the in-repo build recipe is Earthly
+  but the trigger lives in an external orchestrator.
+
+### Changed
+- `ci.configured`: refactored to a data-driven detector list and a
+  unified message format: `"CI configuration detected: <label>."`
+  Previous per-detector ad-hoc messages are gone. Score behaviour is
+  unchanged for all previously-detected configs.
+- First stable PyPI release. Version bumped to 1.0.0 to reflect
+  complete implementation of all nine phases (Plugin API, SARIF,
+  stable JSON schema v1).
+
+## [0.9.0] - Phase 9: Plugin API, SARIF, stable contract
+
+### Added
+- Custom check plugins via `.agent_readiness_checks/` directory (local plugins)
+- Entry-point plugins via `agent_readiness.checks` group in `importlib.metadata`
+- SARIF 2.1.0 export (`--sarif FILE`) for GitHub Code Scanning integration
+- `Report.delta` field for baseline comparison
+- `Report.schema=1` stability documentation (will bump to 2 on next breaking change)
+
+### Changed
+- Plugin loading happens before `_ensure_loaded()` so plugins register cleanly
+- `models.py`: add `delta` field to Report for `--baseline` delta display
+
+## [0.8.0] - Phase 8: Distribution
+
+### Added
+- PyPI classifiers and keywords in `pyproject.toml`
+- `.github/workflows/ci.yml` for the project itself (lint + test + dogfood scan)
+- `validate/README.md` describing the planned validation study methodology
+
+## [0.7.0] - Phase 7: HTML report renderer and badge generation
+
+### Added
+- `src/agent_readiness/renderers/html_renderer.py`: Jinja2-based HTML report
+  (optional dep: `pip install agent-readiness[report]`)
+- `src/agent_readiness/renderers/sarif.py`: SARIF 2.1.0 export
+- CLI `--report FILE`: write HTML report
+- CLI `--badge FILE`: write shields.io-style SVG badge
+- CLI `--sarif FILE`: write SARIF output
+
+## [0.65.0] - Phase 6: CLI surface and configurability
+
+### Added
+- `init` command: writes `.agent-readiness.toml` with commented defaults
+- `src/agent_readiness/config.py`: load and parse `.agent-readiness.toml`
+- CLI `--weights FILE`: override pillar weights from a TOML file
+- CLI `--only CHECKS`: filter to specific check IDs or pillar names
+- CLI `--baseline FILE`: load previous JSON report and show score delta
+- CLI `--fail-below N`: exit 1 when overall score < N (CI gate)
+
+## [0.5.0] - Phase 5: Complexity and churn
+
+### Added
+- `git.churn_hotspots` check (CogLoad, weight=0.6): files changed >10 times
+  AND >200 lines are flagged as hotspots; `not_measured` if <5 commits
+- `code.complexity` check (CogLoad, weight=0.7): cyclomatic complexity via
+  lizard; `not_measured` if lizard not installed
+- Optional extras in `pyproject.toml`: `report`, `complexity`, `full`
+
+## [0.4.0] - Phase 4: Feedback signals
+
+### Added
+- `typecheck.configured` check (Feedback, weight=0.9): mypy.ini, pyrightconfig.json,
+  tsconfig.json, or `[tool.mypy]` in pyproject.toml
+- `lint.configured` check (Feedback, weight=0.9): ruff.toml, .eslintrc, .golangci.yml,
+  or `[tool.ruff]` in pyproject.toml
+- `gitignore.covers_junk` check (Safety, weight=1.0): .gitignore covering
+  __pycache__, .env, node_modules, dist/
+- Good fixture: mypy.ini, ruff.toml, .gitignore
+
+## [0.35.0] - Phase 3.5: Flow completeness
+
+### Added
+- `entry_points.detected` check (CogLoad, weight=0.8): main.py, index.js, cmd/, etc.
+- `env.example_parity` check (Flow, weight=0.9): .env.example when env vars used
+- `ci.configured` check (Feedback, weight=0.9): GitHub Actions, CircleCI, etc.
+- `setup.command_count` check (Flow, weight=0.7): ≤2 setup commands is ideal
+- `naming.search_precision` check (CogLoad, weight=0.6): no utils/helpers/manager
+- Good fixture: .github/workflows/ci.yml, src/main.py, src/__init__.py, .env.example
+- Good fixture now scores 100.0 overall
+
+## [0.3.0] - Phase 3: Context-window economics and repo shape
+
+### Added
+- `RepoContext.orientation_tokens` cached property (chars/4 heuristic)
+- `repo_shape.top_level_count` check (CogLoad, weight=0.8)
+- `repo_shape.large_files` check (CogLoad, weight=0.8)
+- `repo_shape.token_budget` check (CogLoad, weight=0.7)
+
+## [0.2.0] - Phase 2: Docker sandbox and static manifest checks
+
+### Added
+- `manifest.detected` check (Feedback, weight=1.0): pyproject.toml, package.json, etc.
+- `manifest.lockfile_present` check (Feedback, weight=1.0): poetry.lock, uv.lock, etc.
+- `git.has_history` check (Flow, weight=1.0): scores by commit count
+- Full `DockerSandbox.run()`, `detect_docker_native()`, `resolve_image()` implementations
+- `src/agent_readiness/config.py`: load `.agent-readiness.toml`
+- `src/agent_readiness/plugins.py`: plugin discovery
+- CLI `--run` flag fully implemented (preflight → docker-native check → run)
+- Good fixture: pyproject.toml, uv.lock, CLAUDE.md
+- Fixed `RepoContext.is_git_repo` to detect parent-repo git via `git rev-parse`
+
+## [0.1.0] - Phase 1: Five static checks
+
+### Added
+- `readme.has_run_instructions` check (CogLoad, weight=1.0)
+- `agent_docs.present` check (CogLoad, weight=1.0)
+- `test_command.discoverable` check (Feedback, weight=1.0)
+- `headless.no_setup_prompts` check (Flow, weight=1.0)
+- `secrets.basic_scan` check (Safety, weight=1.0): caps overall at 30 on ERROR, 75 on WARN
+- `RepoContext`: cached file inventory, git helpers
+- `scorer.score()`: weighted pillar means + safety cap
+- Terminal renderer (rich + plain-text fallback)
+- JSON renderer (stable schema v1)
+- `scan`, `list-checks`, `explain` CLI commands
+- Good and bare test fixtures
+- Safety cap behaviour tests
+
+[Unreleased]: https://github.com/harrydaihaolin/agent-readiness/compare/v1.0.0...HEAD
+[1.0.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.9.0...v1.0.0
+[0.9.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.8.0...v0.9.0
+[0.8.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.7.0...v0.8.0
+[0.7.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.65.0...v0.7.0
+[0.65.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.5.0...v0.65.0
+[0.5.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.4.0...v0.5.0
+[0.4.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.35.0...v0.4.0
+[0.35.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.3.0...v0.35.0
+[0.3.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.2.0...v0.3.0
+[0.2.0]: https://github.com/harrydaihaolin/agent-readiness/compare/v0.1.0...v0.2.0
+[0.1.0]: https://github.com/harrydaihaolin/agent-readiness/releases/tag/v0.1.0

agent_readiness-1.0.0/CLAUDE.md

@@ -0,0 +1,41 @@
+# Claude Code guide
+
+Conventions specific to Claude Code working in this repository.
+For general agent conventions see [`AGENTS.md`](./AGENTS.md).
+
+## Quick start
+
+```bash
+make dev        # install dev deps (pip install -e ".[dev]")
+make test       # run tests (unittest discover, no pytest required)
+make lint       # ruff check src tests
+PYTHONPATH=src python3 -m agent_readiness.cli scan .   # dogfood the tool on itself
+```
+
+## Key invariants
+
+- **Dogfood on every iteration.** Run `PYTHONPATH=src python3 -m agent_readiness.cli scan .`
+  after each change. The score should not regress. Fix friction before moving on.
+- **Headless-first.** The CLI has no interactive prompts. `--json` output is stable
+  (schema-versioned). Exit codes mean things. Do not break these contracts.
+- **Static checks only in Phase 1–3.** Checks that execute repo code are gated behind
+  `--run` and run inside Docker. Never shell out to target-repo code from a static check.
+
+## Adding a check (summary)
+
+1. `src/agent_readiness/checks/<name>.py` — `@register(...)` decorated function returning `CheckResult`
+2. Import it inside `_ensure_loaded()` in `src/agent_readiness/checks/__init__.py`
+3. Update `RUBRIC.md` and `PLAN.md` (check must have a name-able agent failure mode)
+4. Add or extend a fixture; update snapshot assertions if scores shift
+
+## Do-not-touch without a reason
+
+- Default pillar weights in `scorer.py` — changing these shifts every reported score
+- `Report.schema` integer in `models.py` — bump only on intentional breaking changes
+- Sandbox contracts in `sandbox.py` — hard rules live in `SANDBOX.md`
+
+## Commit and branch conventions
+
+- Feature branches: `feat/<short-description>`
+- Conventional Commits style where reasonable
+- Run `make lint && make test` before committing

agent_readiness-1.0.0/CODEOWNERS

@@ -0,0 +1,2 @@
+# CODEOWNERS
+* @harrydaihaolin

agent_readiness-1.0.0/Makefile

@@ -0,0 +1,26 @@
+.PHONY: install dev test lint clean build release
+
+install:
+	pip install -e .
+
+dev:
+	pip install -e ".[dev]"
+
+test:
+	PYTHONPATH=src python3 -m unittest discover -s tests -v
+
+lint:
+	ruff check src tests
+
+clean:
+	rm -rf build dist *.egg-info src/*.egg-info .pytest_cache .ruff_cache
+	find . -type d -name __pycache__ -exec rm -rf {} +
+
+build: clean
+	python -m build
+
+release: build
+	@echo "Artifacts in dist/:"
+	@ls -lh dist/
+	@echo ""
+	@echo "Next: git tag v$$(python -c 'import agent_readiness; print(agent_readiness.__version__)') && git push origin --tags"

agent_readiness-1.0.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: agent-readiness
+Version: 1.0.0
+Summary: Benchmark how agent-ready a code repository is for LLM coding agents.
+Project-URL: Homepage, https://github.com/harrydaihaolin/agent-readiness
+Project-URL: Repository, https://github.com/harrydaihaolin/agent-readiness
+Project-URL: Changelog, https://github.com/harrydaihaolin/agent-readiness/blob/main/CHANGELOG.md
+Project-URL: Bug Tracker, https://github.com/harrydaihaolin/agent-readiness/issues
+Project-URL: Documentation, https://github.com/harrydaihaolin/agent-readiness#readme
+Author: agent-readiness contributors
+License: MIT
+Keywords: agents,ai,benchmark,code-quality,developer-experience
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.11
+Requires-Dist: click>=8.1
+Requires-Dist: rich>=13.7
+Provides-Extra: complexity
+Requires-Dist: lizard>=1.17; extra == 'complexity'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Provides-Extra: full
+Requires-Dist: jinja2>=3.1; extra == 'full'
+Requires-Dist: lizard>=1.17; extra == 'full'
+Requires-Dist: mcp>=1.0; extra == 'full'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0; extra == 'mcp'
+Provides-Extra: report
+Requires-Dist: jinja2>=3.1; extra == 'report'
+Description-Content-Type: text/markdown
+
+# agent-readiness
+
+**A benchmark for AI agent readiness of a code repository.**
+
+You bought the seats. Your team is using Claude Code, Cursor, Copilot, Cline.
+And the agents keep going off the rails on *your* codebase.
+
+The model is the variable you can't change. The repo is what you can.
+
+`agent-readiness` scans a repository and scores how ready it is for AI
+coding agents — across cognitive load, feedback loops, and flow — then
+hands you a prioritised punchlist of fixes. Like Lighthouse, but for AI
+agent readiness instead of page load.
+
+```
+$ agent-readiness scan .
+
+AI Readiness  62 / 100
+
+  Cognitive load     70 / 100
+  Feedback loops     40 / 100   ← biggest drag
+  Flow & reliability 75 / 100
+  Safety             OK
+
+Top friction (fix these first):
+  1. test_command.discoverable — no test invocation found in Makefile,
+     package.json, or pyproject.toml
+  2. agent_docs.present — no AGENTS.md / CLAUDE.md / .cursorrules at root
+  3. headless.no_setup_prompts — README mentions "log in to the dashboard"
+     during setup; agents can't traverse this
+```
+
+## Design principles
+
+**Agents are headless.** We assume the agent has stdin / stdout / files /
+git / HTTP and nothing else. No browser, no dashboard, no clickable
+button. If important state is reachable only through a UI, it's invisible
+to the agent — and the repo loses points wherever that's true.
+
+This applies to our own tool, too. `agent-readiness` is fully headless:
+no required interactive prompts, stable JSON via `--json`, exit codes
+that mean things, machine-readable findings.
+
+**Code quality counts only where it predicts agent success.** Mega-files,
+ambiguous names, dead code, missing types — those have direct lines to
+agent failure modes and get measured. We don't reproduce the full
+SonarQube taxonomy. Other tools do that well.
+
+**Run untrusted code in Docker, always.** Any check that executes code
+from the target repo runs inside a sandboxed container. See
+[`docs/SANDBOX.md`](./docs/SANDBOX.md).
+
+## What gets measured
+
+See [`docs/RUBRIC.md`](./docs/RUBRIC.md) for the full definition. Short version:
+
+| Pillar | What it captures |
+|---|---|
+| **Cognitive load** | What the agent must absorb to make a correct change. |
+| **Feedback loops** | How fast and clear is the signal after a change. |
+| **Flow / reliability** | Headless walkability + how often friction outside the task blocks the agent. |
+| **Safety & trust** | Secrets, destructive scripts, gitignore hygiene. (Cap, not weight.) |
+
+## This repo's score
+
+Dogfooding: `agent-readiness scan .` run against this repository itself.
+
+```
+╭─────────────────────────────╮
+│  AI Readiness  100.0 / 100  │
+╰─────────────────────────────╯
+ Cognitive load      100.0  ████████████████████
+ Feedback loops      100.0  ████████████████████
+ Flow & reliability  100.0  ████████████████████
+ Safety              100.0  ████████████████████
+
+No findings. Looking good.
+```
+
+Score updated after each iteration as part of the development workflow.
+
+## Usage
+
+```
+# Static scan (no Docker needed)
+agent-readiness scan .
+agent-readiness scan . --json
+agent-readiness scan . --fail-below 70        # exit 1 if score < 70 (CI gate)
+agent-readiness scan . --only feedback        # filter to one pillar
+agent-readiness scan . --baseline prev.json   # diff against a previous run
+agent-readiness scan . --report report.html   # HTML report (requires jinja2)
+agent-readiness scan . --badge badge.svg      # score badge SVG
+agent-readiness scan . --sarif findings.sarif # SARIF for GitHub code scanning
+
+# Runtime scan (executes tests inside Docker)
+agent-readiness scan . --run
+
+# Other commands
+agent-readiness list-checks
+agent-readiness explain manifest.detected
+agent-readiness init                          # write .agent-readiness.toml
+```
+
+## Status
+
+All phases implemented (v0.1–v0.9). 22 checks across 4 pillars, Docker
+sandbox, HTML + SARIF renderers, CLI surface, plugin API. See
+[`docs/PLAN.md`](./docs/PLAN.md) for the full roadmap and
+[`CHANGELOG.md`](./CHANGELOG.md) for per-phase release notes.