ai-dev-cli-tools 0.5.0a1__tar.gz

ai_dev_cli_tools-0.5.0a1/.github/workflows/ci.yml

@@ -0,0 +1,71 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src tests
+      - run: coverage run -m pytest
+      - run: coverage report --fail-under=90
+      - run: python -m build
+      - run: python scripts/test_installed_package.py
+      - run: python scripts/validate_ci.py
+      - run: ai-dev --version
+      - run: ai-dev doctor --json
+      - run: ai-dev scan --json
+      - run: ai-dev bootstrap --explain --json
+      - run: ai-dev capabilities --json
+      - run: ai-dev context build --explain --json
+      - run: ai-dev git inspect --json
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: ai-dev-reports-${{ matrix.os }}-${{ matrix.python-version }}
+          path: |
+            .ai/reports
+            .ai/logs
+          if-no-files-found: ignore
+  toolchain-e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+      - uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: "17"
+      - uses: dtolnay/rust-toolchain@stable
+      - uses: shivammathur/setup-php@v2
+        with:
+          php-version: "8.3"
+          tools: composer
+      - uses: gradle/actions/setup-gradle@v4
+        with:
+          gradle-version: "8.10"
+      - run: python -m pip install -e ".[dev]"
+      - name: Execute real fixture toolchains
+        env:
+          RUN_TOOLCHAIN_E2E: "1"
+          E2E_TOOLCHAINS: python,node,rust,maven,gradle,php
+        run: python -m pytest tests/integration/test_toolchain_e2e.py -q

ai_dev_cli_tools-0.5.0a1/.github/workflows/docs.yml

@@ -0,0 +1,20 @@
+name: Docs
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  docs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install -e ".[dev]"
+      - run: python -m ai_dev_tools.cli --help
+      - run: python -m ai_dev_tools.cli check --help
+      - run: test -s README.md
+      - run: test -s docs/ARCHITECTURE.md
+      - run: test -s docs/REPORT_SCHEMA.md

ai_dev_cli_tools-0.5.0a1/.github/workflows/publish-pypi.yml

@@ -0,0 +1,85 @@
+name: Publish PyPI
+
+on:
+  release:
+    types:
+      - published
+
+permissions:
+  contents: read
+
+jobs:
+  validate-release:
+    name: Validate manually promoted release artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.release.tag_name }}
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - name: Download artifacts attached by the TestPyPI workflow
+        env:
+          GH_TOKEN: ${{ github.token }}
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: >-
+          gh release download "$RELEASE_TAG"
+          --pattern "ai_dev_cli_tools-*"
+          --dir dist/
+      - name: Validate tag and release artifacts
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: |
+          python -m pip install --upgrade twine
+          python -m twine check dist/*
+          python scripts/validate_release.py --tag "$RELEASE_TAG" --dist dist
+      - name: Upload validated production artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: pypi-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-pypi:
+    name: Publish manually approved release to PyPI
+    needs: validate-release
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/ai-dev-cli-tools
+    permissions:
+      id-token: write
+    steps:
+      - name: Download validated production artifact
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: pypi-distributions
+          path: dist/
+      - name: Publish distribution to PyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          packages-dir: dist/
+
+  verify-pypi:
+    name: Verify PyPI pipx installation
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+          ref: ${{ github.event.release.tag_name }}
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - name: Install and smoke test from PyPI through pipx
+        env:
+          RELEASE_TAG: ${{ github.event.release.tag_name }}
+        run: >-
+          python scripts/verify_published_package.py
+          --version "${RELEASE_TAG#v}"
+          --index-url https://pypi.org/simple/
+          --installer pipx

ai_dev_cli_tools-0.5.0a1/.github/workflows/release.yml

@@ -0,0 +1,102 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and validate distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - name: Validate tag and source version
+        run: python scripts/validate_release.py --tag "$GITHUB_REF_NAME"
+      - name: Install release tooling
+        run: python -m pip install --upgrade build twine
+      - name: Build wheel and source distribution
+        run: python -m build
+      - name: Validate distributions
+        run: |
+          python -m twine check dist/*
+          python scripts/validate_release.py --tag "$GITHUB_REF_NAME" --dist dist
+          python scripts/test_installed_package.py
+      - name: Upload immutable distribution artifact
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+          retention-days: 7
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/ai-dev-cli-tools
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distribution artifact
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Publish distribution to TestPyPI
+        uses: pypa/gh-action-pypi-publish@dc37677b2e1c63e2034f94d8a5b11f265b73ba33 # release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+          packages-dir: dist/
+          attestations: false
+
+  verify-testpypi:
+    name: Verify TestPyPI installation
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - name: Install and smoke test from TestPyPI
+        run: >-
+          python scripts/verify_published_package.py
+          --version "${GITHUB_REF_NAME#v}"
+          --index-url https://test.pypi.org/simple/
+
+  draft-release:
+    name: Create manually promoted release draft
+    needs: verify-testpypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - name: Download TestPyPI-verified distribution artifact
+        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        with:
+          name: python-package-distributions
+          path: dist/
+      - name: Create draft GitHub release for manual PyPI promotion
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >-
+          gh release create "$GITHUB_REF_NAME"
+          dist/*
+          --draft
+          --prerelease
+          --verify-tag
+          --generate-notes
+          --title "ai-dev $GITHUB_REF_NAME"

ai_dev_cli_tools-0.5.0a1/.gitignore

@@ -0,0 +1,16 @@
+.ai/tmp/
+.ai/runtime/
+.ai/cache/
+.ai/context/
+.ai/logs/
+.ai/reports/
+.coverage
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+*.egg-info/
+__pycache__/
+*.py[cod]

ai_dev_cli_tools-0.5.0a1/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+## Unreleased
+
+## 0.5.0a1 - 2026-08-10
+
+- Add workspace models and isolated check/bootstrap routing for mixed monorepos.
+- Add cross-platform mixed-monorepo and Git path fixtures covering spaces, Unicode, rename, deletion, and non-UTF-8 output.
+- Add runner failure matrices and real Python, Node, Rust, Maven, Gradle, and Composer fixture execution in CI.
+- Detect and validate Python, Node.js, Java, Rust, and PHP runtime requirements.
+- Implement safe managed `run` and `stop` with supervisor-owned process termination.
+- Add HTTP/TCP readiness probes, bounded startup logs, and readiness-timeout cleanup.
+- Add bounded parallel check execution with `--jobs`.
+- Add a versioned repository index and content-addressed validation cache with bounded retention.
+- Add incremental context manifests and `context build --incremental`.
+- Add AST-aware Python symbol snippets for large context files.
+- Add minimal, debug, review, and full context profiles.
+- Add local diagnostics, efficiency estimates, a stable agent contract, and JSON integration example.
+- Add dependency-free completion generators for Bash, Zsh, Fish, and PowerShell.
+- Add stable failure signatures and a machine-readable report JSON Schema.
+- Add an extensible tool-output parser registry with deterministic precedence.
+- Add compatibility fixtures and prevent cross-line test-count overcounting.
+- Apply defense-in-depth secret masking to command logs, diagnostics, runtime streams, and report writers.
+- Raise and enforce the coverage threshold to 90%.
+- Add agent-efficiency and execution TODO roadmaps.
+
+## 0.4.0
+
+- Add `ai-dev bootstrap` with safe explain, dry-run, and execution modes.
+- Support bootstrap strategies for Python, Node.js, Maven, Gradle, Rust, and PHP.
+- Add guarded `.env.example` to `.env` creation via `--create-env`.
+- Add installed-wheel entrypoint smoke validation to local and CI standards.
+- Keep cross-platform CI marked as externally blocked until GitHub Actions jobs actually run.
+## 0.3.0
+
+- Add `ai-dev context build` for bounded local AI context packages.
+- Write `.ai/context/context-latest.md` and `.ai/context/context-latest.json` artifacts.
+- Reuse scan, repository map, git inspect, changed-test selection, validation planning, and secret masking.
+- Keep monorepo detection experimental, per-subproject runner isolation planned, and runtime validation partial.
+## 0.2.0
+
+- Add schema 1.1 reports with exit codes and metadata.
+- Add tool-specific output parser layer with fixtures for Python, JavaScript, Java, Rust, and PHP logs.
+- Add `ai-dev capabilities` and `ai-dev check --explain`.
+- Add `logs summarize <path> --tool auto|name` with a 50 MB input limit.
+- Improve changed-file strategies with configuration-change and changed-test-direct reporting.
+- Prepare package version 0.2.0 without creating a release.
+
+## 0.1.0
+
+- Initial private foundation for cross-platform AI development CLI helpers.

ai_dev_cli_tools-0.5.0a1/CONTRIBUTING.md

@@ -0,0 +1,18 @@
+# Contributing
+
+Keep changes small, typed, tested, and conservative. Runtime code should avoid platform-specific assumptions and prefer `pathlib` for paths.
+
+Before pushing a larger stage, run:
+
+```bash
+python -m ruff check .
+python -m mypy src tests scripts
+python -m coverage run -m pytest
+python -m coverage report --fail-under=90
+python -m build
+python scripts/validate_ci.py
+python scripts/test_installed_package.py
+git diff --check
+```
+
+The installed package smoke test must use a built wheel, a clean virtual environment, and the installed `ai-dev` entrypoint. Do not replace it with editable install or `PYTHONPATH` smoke tests.

ai_dev_cli_tools-0.5.0a1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mateusz Lewandowski
+
+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_dev_cli_tools-0.5.0a1/Makefile

@@ -0,0 +1,17 @@
+.PHONY: test lint typecheck coverage build
+
+test:
+	python -m pytest
+
+lint:
+	ruff check .
+
+typecheck:
+	mypy src tests
+
+coverage:
+	coverage run -m pytest
+	coverage report --fail-under=90
+
+build:
+	python -m build

ai_dev_cli_tools-0.5.0a1/PKG-INFO

@@ -0,0 +1,240 @@
+Metadata-Version: 2.4
+Name: ai-dev-cli-tools
+Version: 0.5.0a1
+Summary: Cross-platform CLI helpers that give AI coding agents concise, deterministic development reports.
+Project-URL: Homepage, https://github.com/MatthiasLew/ai-dev-cli-tools
+Project-URL: Repository, https://github.com/MatthiasLew/ai-dev-cli-tools
+Project-URL: Issues, https://github.com/MatthiasLew/ai-dev-cli-tools/issues
+Project-URL: Changelog, https://github.com/MatthiasLew/ai-dev-cli-tools/blob/main/CHANGELOG.md
+Author: Mateusz Lewandowski
+License: MIT
+License-File: LICENSE
+Keywords: agents,ai,automation,cli,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+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
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: coverage[toml]>=7.6; extra == 'dev'
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.3; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# AI Dev CLI Tools
+
+Cross-platform Python CLI helpers for AI coding agents and humans who want concise, deterministic development reports instead of huge logs.
+
+`ai-dev` runs repeatable project checks locally, stores full logs under `.ai/logs/`, and returns compact Markdown/JSON summaries under `.ai/reports/`.
+
+## Problem
+
+AI coding agents often spend tokens reading full test output, repository trees, dependency noise, repeated warnings, and raw Git diffs. This project follows one rule:
+
+```text
+Scripts do the work and collect data.
+AI reads a short report and decides what to do next.
+Full logs stay on disk until needed.
+
+Generated state under `.ai/logs/`, `.ai/reports/`, `.ai/context/`, `.ai/cache/`,
+`.ai/runtime/`, and `.ai/tmp/` is local and ignored by Git. Logs, reports, and context
+artifacts may be removed when no longer needed; cache, runtime, and temporary state must always
+be safe for `ai-dev` to recreate.
+```
+
+## Install
+
+```bash
+python -m pip install --upgrade pipx
+pipx install ai-dev-cli-tools==0.5.0a1
+ai-dev --help
+```
+
+For a source checkout before the public alpha is published, use `pipx install .`. See
+`docs/DISTRIBUTION.md` for the Trusted Publishing and upgrade policy.
+
+For development:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Windows
+
+```powershell
+.\ai.ps1 doctor
+ai-dev scan --project "C:\path with spaces\project"
+```
+
+## Linux and macOS
+
+```bash
+./ai.sh doctor
+ai-dev check --mode fast --project "/path/with spaces/project"
+```
+
+## Commands
+
+```bash
+ai-dev doctor
+ai-dev scan
+ai-dev map --max-files 500 --max-depth 6
+ai-dev check --mode fast
+ai-dev check --mode changed  # reports changed files and falls back safely when test mapping is uncertain
+ai-dev check --mode full --jobs 4
+ai-dev check --mode changed --policy feedback-first --resume
+ai-dev index update
+ai-dev cache status
+ai-dev baseline create main
+ai-dev baseline compare main
+ai-dev explain issue:<id> --tail 100
+ai-dev feedback --task "fix authentication timeout"
+ai-dev session status
+ai-dev diagnostics
+ai-dev completion bash
+ai-dev test affected
+ai-dev logs summarize
+ai-dev context build
+ai-dev git status
+ai-dev git inspect
+ai-dev finish
+```
+
+All commands support `--project`, `--json`, `--quiet`, `--help`, and `--version` at the top level.
+
+
+## Bootstrap
+
+`ai-dev bootstrap` prepares a detected project with conservative, project-local commands. Use `--explain` to see the plan without modifications, `--dry-run` to validate planning without executing modifying commands, and `--create-env` to allow copying `.env.example` to `.env` only when `.env` is missing.
+
+Supported strategies include Python uv, Poetry, pip with `pyproject.toml`, pip with `requirements.txt`, Node npm/pnpm/Yarn, Maven wrapper or system Maven, Gradle wrapper or system Gradle, Cargo, and Composer.
+
+See `docs/BOOTSTRAP.md` for safety rules and configuration.
+
+## Managed application runtime
+
+`ai-dev run` supports explain, dry-run, foreground, and supervised background modes.
+`ai-dev stop` sends a token-authenticated request to the matching local supervisor and never
+kills an arbitrary PID read from stale state. See `docs/RUNTIME.md`.
+
+## Context Builder
+
+`ai-dev context build` creates a bounded local context package for coding agents without calling any LLM, embedding API, or cloud service.
+
+```bash
+ai-dev context build --task "fix auth tests"
+ai-dev context build --changed-only --max-chars 50000
+ai-dev context build --incremental  # emits only candidates changed since the last pack
+ai-dev context build --profile review
+ai-dev context build --include "src/**/*.py" --exclude "tests/fixtures/**"
+ai-dev context build --explain --json
+```
+
+Artifacts are written to `.ai/context/context-latest.md` and `.ai/context/context-latest.json` by default. The builder includes detected technologies, git state, changed files, related tests, validation plan, recent commits, selected snippets, limited diffs, latest check errors, masked secret findings, and budget/truncation metadata. Large Python files use AST-aware symbol snippets with line ranges instead of blindly returning only the beginning of the file.
+
+Incremental mode stores a schema-versioned manifest under `.ai/cache/` and reports changed versus reused files. Default limits are `--max-chars 50000`, `--max-files 30`, `--max-file-chars 8000`, and `--max-diff-chars 15000`. Secret-bearing and generated paths such as `.env`, private keys, caches, build output, `.ai/logs`, and `.ai/reports` are excluded from snippets.
+## Reports and Logs
+
+Validation results are cached by default using repository, command, workspace, runtime, and platform fingerprints; use `check --no-cache` to force execution. `check --resume` reuses only exact successful checkpoint fingerprints. `--policy feedback-first` runs cheaper waves first and cancels later expensive waves after a required failure; `complete` retains comprehensive execution. `index status/update/rebuild` manages the reusable repository index, while `cache status/prune/clear` provides bounded local cache maintenance. See `docs/CACHE_AND_INDEX.md`.
+
+Short reports are written to `.ai/reports/` as Markdown and JSON. Full command output is written to `.ai/logs/` and ignored by Git. Check summaries include exit codes, durations, first failure hints, grouped repeated messages, test counts, and full log paths.
+
+JSON reports use schema `1.1` with `schema_version`, `tool_version`, `command`, `status`, `exit_code`, timestamps, `project_root`, `summary`, `issues`, `artifacts`, and `metadata`.
+
+`ai-dev feedback` combines Git changes, changed validation, incremental context, focused rerun hints, stage timings, and local session state into one compact agent protocol report.
+
+Every expandable issue, check, file, snippet, diff, workspace, and artifact receives a stable local `evidence_id`. The report metadata lists references; `ai-dev explain <evidence-id> --tail 100` retrieves only that evidence. `ai-dev baseline create <name>` stores a compact local snapshot under `.ai/cache/baselines/`, and `baseline compare <name>` leads with new/resolved failures, issue codes, and status regressions.
+
+## Auto Detection
+
+`scan` detects Python, Node.js, Java, Rust, PHP, Docker, Make, CI workflows, package managers, scripts, entrypoints, tests, lint, formatters, type checkers, and `.env.example` variables.
+
+Supported examples:
+
+- Python: `pyproject.toml`, `requirements.txt`, `pytest`, `ruff`, `black`, `mypy`, `coverage`.
+- Node.js: `package.json`, npm, pnpm, yarn, Jest, Vitest, ESLint, Prettier, TypeScript.
+- Java: Maven, Gradle, tests, Checkstyle, SpotBugs, JaCoCo when configured.
+- Rust: Cargo test, fmt, clippy.
+- PHP: Composer, PHPUnit, PHPStan, PHP-CS-Fixer when configured.
+
+## Configuration
+
+Optional `.ai-dev-tools.toml`:
+
+```toml
+[project]
+name = "example-project"
+
+[commands]
+test = "pytest"
+lint = "ruff check ."
+typecheck = "mypy src"
+
+[ignore]
+paths = ["node_modules", ".venv", "dist", "build"]
+
+[reports]
+directory = ".ai/reports"
+logs_directory = ".ai/logs"
+```
+
+Configuration takes precedence over auto detection. Invalid or unknown configuration is reported through `config_warnings` instead of crashing normal scans.
+## Local Validation
+
+Before pushing a larger stage, run:
+
+```bash
+python -m ruff check .
+python -m mypy src tests scripts
+python -m coverage run -m pytest
+python -m coverage report --fail-under=90
+python -m build
+python scripts/validate_ci.py
+python scripts/test_installed_package.py
+git diff --check
+```
+
+`python scripts/test_installed_package.py` rebuilds the wheel, installs only that wheel into a clean virtual environment in a path containing spaces, and verifies the installed `ai-dev` entrypoint without editable install or `PYTHONPATH`.
+
+## Command Status
+
+| Command | Status |
+| --- | --- |
+| doctor | implemented |
+| scan | implemented |
+| map | implemented |
+| check | implemented |
+| check --explain | implemented |
+| test affected | implemented |
+| index status/update/rebuild | implemented |
+| cache status/prune/clear | implemented |
+| logs summarize | implemented |
+| context build | implemented |
+| diagnostics | implemented |
+| capabilities | implemented |
+| git status | implemented |
+| git inspect | implemented |
+| finish | implemented |
+| bootstrap | implemented |
+| run | implemented |
+| stop | implemented |
+
+## Scope Notes
+
+- Monorepo/workspace detection and per-subproject command routing: implemented.
+- Per-subproject check and bootstrap working directories: implemented.
+- Runtime version validation: partial.
+- `context build` is implemented as a bounded local context pack builder.
+- `bootstrap` is implemented as a conservative local setup planner/executor.
+- Auto-commit, auto-push, and GUI remain out of scope or planned.
+
+## Intentional Limits
+Version 0.5.0a1 does not reset, clean, commit, push, merge, clone organizations, synchronize repositories, delete containers, publish releases, or remove user files.
+
+Shell completion scripts are generated with `ai-dev completion bash|zsh|fish|powershell` and can be sourced or installed using the normal mechanism for the selected shell.