ai-dev-cli-tools 0.5.0a1__tar.gz → 1.1.0__tar.gz

ai_dev_cli_tools-1.1.0/.github/workflows/ci.yml

@@ -0,0 +1,120 @@
+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@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -c requirements-dev.lock -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@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        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@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "22"
+      - uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c # v6.0.0
+        with:
+          distribution: temurin
+          java-version: "17"
+      - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable 2026-08-31
+      - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        with:
+          php-version: "8.3"
+          tools: composer
+      - uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb # v6.3.0
+        with:
+          gradle-version: "8.10"
+      - run: python -m pip install -c requirements-dev.lock -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
+
+  agent-corpus:
+    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"
+      - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
+      - name: Run real-agent regression corpus
+        run: >-
+          ai-dev benchmark corpus
+          --manifest examples/benchmarks/agent-corpus.json
+          --trials 3
+          --timeout 60
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: agent-corpus-results
+          path: .ai/benchmarks
+          if-no-files-found: error
+
+  agent-report:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
+      - name: Build bounded agent plan
+        run: ai-dev plan --task "Review this commit" --json
+      - name: Export SARIF
+        run: ai-dev sarif --input .ai/reports/agent-plan.json --output .ai/reports/ai-dev.sarif
+      - name: Add agent plan to job summary
+        run: cat .ai/reports/agent-plan.md >> "$GITHUB_STEP_SUMMARY"
+      - name: Upload SARIF to GitHub code scanning
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
+        with:
+          sarif_file: .ai/reports/ai-dev.sarif

{ai_dev_cli_tools-0.5.0a1 → ai_dev_cli_tools-1.1.0}/.github/workflows/docs.yml

@@ -8,11 +8,11 @@ jobs:
   docs:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-python@v5
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
         with:
           python-version: "3.12"
-      - run: python -m pip install -e ".[dev]"
+      - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
       - run: python -m ai_dev_tools.cli --help
       - run: python -m ai_dev_tools.cli check --help
       - run: test -s README.md

{ai_dev_cli_tools-0.5.0a1 → ai_dev_cli_tools-1.1.0}/.github/workflows/publish-pypi.yml

@@ -10,6 +10,7 @@ permissions:
 
 jobs:
   validate-release:
+    if: github.event.release.prerelease == false
     name: Validate manually promoted release artifacts
     runs-on: ubuntu-latest
     steps:
@@ -36,7 +37,7 @@ jobs:
           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
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: pypi-distributions
           path: dist/
@@ -44,6 +45,7 @@ jobs:
           retention-days: 7
 
   publish-pypi:
+    if: github.event.release.prerelease == false
     name: Publish manually approved release to PyPI
     needs: validate-release
     runs-on: ubuntu-latest
@@ -54,7 +56,7 @@ jobs:
       id-token: write
     steps:
       - name: Download validated production artifact
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: pypi-distributions
           path: dist/
@@ -64,6 +66,7 @@ jobs:
           packages-dir: dist/
 
   verify-pypi:
+    if: github.event.release.prerelease == false
     name: Verify PyPI pipx installation
     needs: publish-pypi
     runs-on: ubuntu-latest

{ai_dev_cli_tools-0.5.0a1 → ai_dev_cli_tools-1.1.0}/.github/workflows/release.yml

@@ -31,7 +31,7 @@ jobs:
           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
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: python-package-distributions
           path: dist/
@@ -49,7 +49,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution artifact
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: python-package-distributions
           path: dist/
@@ -84,19 +84,20 @@ jobs:
     permissions:
       contents: write
     steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
       - name: Download TestPyPI-verified distribution artifact
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: python-package-distributions
           path: dist/
-      - name: Create draft GitHub release for manual PyPI promotion
+      - name: Create RC prerelease or stable promotion draft
         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"
+        run: |
+          if [[ "$GITHUB_REF_NAME" == *-rc.* ]]; then
+            gh release create "$GITHUB_REF_NAME" dist/* --prerelease --verify-tag --generate-notes --title "ai-dev $GITHUB_REF_NAME"
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* --draft --verify-tag --generate-notes --title "ai-dev $GITHUB_REF_NAME"
+          fi

{ai_dev_cli_tools-0.5.0a1 → ai_dev_cli_tools-1.1.0}/.gitignore

@@ -1,9 +1,12 @@
 .ai/tmp/
 .ai/runtime/
 .ai/cache/
+.ai/benchmarks/
 .ai/context/
 .ai/logs/
+.ai/performance/
 .ai/reports/
+.ai/release-venv/
 .coverage
 .mypy_cache/
 .pytest_cache/

ai_dev_cli_tools-1.1.0/CHANGELOG.md

@@ -0,0 +1,117 @@
+# Changelog
+
+## 1.1.0 - 2026-08-31
+
+Stable promotion of `1.1.0rc1` after cross-platform CI, benchmark regression gates, and a clean
+TestPyPI installation smoke test.
+
+- Add `plan` and MCP `plan_work` for bounded, preview-only implementation plans with scope,
+  dependencies, validation, risk, policy assessments, and stable evidence references.
+- Add built-in Tree-sitter AST and LSP document-symbol backends alongside the local structural
+  fallback and semantic plugin contract.
+- Add a detached, localhost-authenticated index daemon using native filesystem events, IPC
+  start/status/stop control, lifecycle state, and no periodic repository rescans.
+- Classify command failures and retry only transient infrastructure failures while preserving the
+  first failure and recovery evidence.
+- Add configurable command allow/deny prefixes and impact limits, enforced by checks, bootstrap,
+  and application startup, plus a preview-only `policy assess` command.
+- Extend reproducible benchmarks with precision, recall, false negatives, iterations, files read,
+  reported token metrics, a versioned real-agent corpus, and enforceable regression gates.
+- Add ready project-scoped MCP configurations for Codex, Claude Code, Cursor, and generic clients.
+- Add a loopback-only local dashboard for index, semantic, cache, runtime, daemon, and error health.
+- Add deterministic report-to-SARIF conversion and a GitHub Actions code-scanning summary job.
+- Upgrade and SHA-pin supported GitHub Actions used by CI, docs, and publishing workflows.
+
+## 1.0.0 - 2026-08-31
+
+- Stabilize the local CLI and report schema for the 1.0 release line.
+- Add deterministic `implement` and `docs` context profiles with contract-tested budgets.
+- Add project-scoped `explain --symbol PATH#QUALIFIED_SYMBOL` with bounded content and related tests.
+- Add configuration ownership, generated-source relationships, reverse-dependent traversal, and
+  bounded reason paths to the impact graph.
+- Add nested Java/PHP owner qualification and overload-safe Java member identities.
+- Add dependency-aware, resource-bounded check scheduling with deterministic report order.
+- Safely cancel only subprocesses owned by obsolete watch validations while retaining their logs.
+- Add a pinned development-tool baseline and disable unrelated globally installed pytest-qt hooks.
+- Add an end-to-end regression for ignored virtual environments, CP1250 output, and non-zero check
+  result status consistency.
+- Add retained historical incremental context manifests and `context build --since <context-id>`.
+- Add direct named baseline regression checks through `check --compare` and
+  `context build --compare`.
+- Add bounded shortest reason paths for changed-file, related-test, symbol, and check selection.
+- Exclude `env` and `venv` dependency trees from workspace discovery, make text reports safe on
+  legacy Windows console encodings, and keep non-zero check results from reporting success.
+- Add explainable `auto|always|never` selective retrieval with conservative fallback and related-test false-negative measurement.
+- Add a local observation lifecycle that replaces superseded feedback with expandable content-addressed evidence while retaining current failures, warnings, and final verification.
+- Add a relocatable deterministic prompt-cache layout manifest with stable-prefix fingerprints and OpenAI, Anthropic, and provider-neutral breakpoint recommendations.
+- Add optional exact tiktoken accounting, provider usage normalization, and enforced per-category token budgets for context packs.
+- Add bounded multi-round context refinement driven by failures, changed symbols, dependencies, and expandable evidence.
+- Add opt-in deterministic prose/log deduplication with fail-closed protected-evidence fingerprints.
+- Add owner-qualified Java/PHP methods and Rust impl/trait functions, Java constructor detection,
+  and correct global PHP function classification.
+- Replace the completed historical backlog with an active backlog and mark every roadmap capability
+  as implemented or partial against the supported CLI.
+
+- Document research-backed selective retrieval, prompt-cache layout, observation lifecycle, token accounting, and safe compression priorities.
+- Add local stage timing records, configurable performance budgets, and latest/compare diagnostics.
+- Add versioned real-agent benchmark fixtures for repair, affected tests, multi-turn context, and monorepo routing, with private measured workflow telemetry and published raw trials.
+- Add a dependency-free local MCP STDIO server with focused, bounded project tools.
+- Add symbol-level Python and JavaScript/TypeScript working-tree diffs with compact review contexts.
+- Add local multi-agent task coordination with expiring leases and path-conflict detection.
+- Add conservative Java, Rust, and PHP adapters for context selection and symbol-level diffs.
+
+- Add task-aware JavaScript/TypeScript top-level symbol selection for bounded context packs.
+- Correct capabilities metadata for flaky retries and completed cross-platform CI.
+
+- Add reproducible, correctness-gated local A/B workflow benchmarks and comparison reports.
+- Add foreground watch mode with debounced changed validation and latest-result reports.
+- Add revalidated warm environment state and bootstrap --if-needed.
+- Add opt-in bounded flaky retries with preserved first failures and local history.
+
+## 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 → ai_dev_cli_tools-1.1.0}/CONTRIBUTING.md

@@ -5,6 +5,7 @@ Keep changes small, typed, tested, and conservative. Runtime code should avoid p
 Before pushing a larger stage, run:
 
 ```bash
+python -m pip install -c requirements-dev.lock -e ".[dev]"
 python -m ruff check .
 python -m mypy src tests scripts
 python -m coverage run -m pytest

{ai_dev_cli_tools-0.5.0a1 → ai_dev_cli_tools-1.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: ai-dev-cli-tools
-Version: 0.5.0a1
+Version: 1.1.0
 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
@@ -10,7 +10,7 @@ Author: Mateusz Lewandowski
 License: MIT
 License-File: LICENSE
 Keywords: agents,ai,automation,cli,developer-tools
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Environment :: Console
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
@@ -19,12 +19,17 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.11
+Requires-Dist: watchdog<7,>=4
 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'
+Provides-Extra: semantic
+Requires-Dist: tree-sitter-language-pack>=0.9; extra == 'semantic'
+Provides-Extra: tokenizers
+Requires-Dist: tiktoken>=0.7; extra == 'tokenizers'
 Description-Content-Type: text/markdown
 
 # AI Dev CLI Tools
@@ -52,17 +57,17 @@ be safe for `ai-dev` to recreate.
 
 ```bash
 python -m pip install --upgrade pipx
-pipx install ai-dev-cli-tools==0.5.0a1
+pipx install ai-dev-cli-tools==1.0.0
 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 a source checkout, use `pipx install .`. See `docs/DISTRIBUTION.md` for the Trusted Publishing
+and upgrade policy.
 
 For development:
 
 ```bash
-python -m pip install -e ".[dev]"
+python -m pip install -c requirements-dev.lock -e ".[dev]"
 ```
 
 ## Windows
@@ -89,16 +94,38 @@ 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 check --mode changed --compare main
+ai-dev check --mode changed --retry-flaky 1
+ai-dev check --mode changed --retry-infra 1
+ai-dev plan --task "implement rate limiting" --mode changed
 ai-dev index update
+ai-dev index daemon start
+ai-dev index daemon status
+ai-dev index daemon stop
+ai-dev semantic status
+ai-dev semantic index --backend auto
+ai-dev policy assess -- python -m pytest
+ai-dev sarif --input .ai/reports/agent-plan.json
 ai-dev cache status
+ai-dev cache layout
 ai-dev baseline create main
 ai-dev baseline compare main
+ai-dev benchmark run --suite examples/benchmarks/output-budget-smoke.json --variant baseline
+ai-dev benchmark corpus --manifest examples/benchmarks/agent-corpus.json --trials 3
+ai-dev integrations install all
+ai-dev dashboard serve --port 8765
 ai-dev explain issue:<id> --tail 100
+ai-dev explain --symbol "src/app.py#Application.run" --tail 100
 ai-dev feedback --task "fix authentication timeout"
+ai-dev watch --mode changed --debounce 500
 ai-dev session status
+ai-dev bootstrap --if-needed
+ai-dev environment explain
 ai-dev diagnostics
 ai-dev completion bash
+ai-dev mcp serve
 ai-dev test affected
+ai-dev test flaky
 ai-dev logs summarize
 ai-dev context build
 ai-dev git status
@@ -109,6 +136,27 @@ ai-dev finish
 All commands support `--project`, `--json`, `--quiet`, `--help`, and `--version` at the top level.
 
 
+## Local MCP server
+
+`ai-dev mcp serve` exposes project status, implementation planning, compact feedback, bounded context, validation,
+and progressive evidence as local structured tools for Codex-compatible MCP clients. The STDIO
+server is dependency-free, has no network listener, fixes all calls to one project root, and
+defaults validation to preview-only.
+
+```bash
+codex mcp add ai-dev -- ai-dev --project "/absolute/path/to/project" mcp serve
+```
+
+See `docs/MCP_SERVER.md` for tool schemas, approvals, project-scoped configuration, and
+security boundaries.
+
+For the recommended agent loop—plan, retrieve, implement, validate, and expand only failed
+evidence—see `docs/AGENT_WORKFLOW.md`.
+
+For agents sharing a repository, `ai-dev agents add|claim|heartbeat|release|complete|status`
+maintains an atomic local task board with expiring leases and declared-path conflict detection.
+See `docs/AGENT_COORDINATION.md` for the workflow and safety limits.
+
 ## 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.
@@ -131,25 +179,43 @@ kills an arbitrary PID read from stale state. See `docs/RUNTIME.md`.
 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 --incremental --since <context-id>
+ai-dev context build --compare main
 ai-dev context build --profile review
+ai-dev context build --profile implement
+ai-dev context build --profile docs
+ai-dev context build --retrieval auto --explain  # explains retrieval or abstention
+ai-dev context build --tokenizer o200k_base --token-budget source=8000 --token-budget diffs=2000
+ai-dev context build --refine issue:<id> --refinement-rounds 2 --refinement-max-files 5
+ai-dev context build --compression conservative
 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.
+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, while large JavaScript and TypeScript files use conservative top-level symbol selection instead of blindly returning only the beginning of the file.
+
+Selective retrieval defaults to `auto`: focused includes or changed files can abstain from broad cross-file retrieval, while missing focus, broad configuration changes, and broad task scopes fall back to the full candidate set. Use `--retrieval always` to expand or `--retrieval never` to keep only focused roots and inferred related tests. The JSON and Markdown reports explain the decision and expose a related-test false-negative proxy.
 
-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.
+Install `ai-dev-cli-tools[tokenizers]` to enable exact local `cl100k_base` or `o200k_base` counting. Without that optional extra, accounting uses the explicit UTF-8-bytes/4 estimate and reports a fallback if an exact tokenizer was requested. Repeated `--token-budget category=N` limits source, diffs, tests, logs, maps, history, cached input, or output independently. `--provider-usage <json>` normalizes OpenAI or Anthropic usage fields from a project-local file without network access.
+
+Incremental mode stores the latest schema-versioned manifest plus up to 50 content-addressed
+historical manifests under `.ai/cache/`, and reports changed versus reused files. Pass
+`--since <context-id>` to compare against an explicitly retained context. 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`.
+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; `cache layout` emits a deterministic stable-prefix manifest and provider breakpoint recommendations. 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.
+`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. Its observation lifecycle keeps the current failure, unresolved warnings, or final verification inline while replacing superseded results with content-addressed IDs expandable through `ai-dev explain`; see `docs/OBSERVATION_LIFECYCLE.md`.
 
-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.
+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. Pass `--compare <name>` to `check` or `context build` to apply that regression contract directly to the current report. Reproducible local A/B suites use benchmark run and benchmark compare; see docs/BENCHMARKS.md.
+Research-backed context and token-efficiency recommendations are documented in `docs/TOKEN_EFFICIENCY_RESEARCH.md`.
 
 ## Auto Detection
 
@@ -182,6 +248,12 @@ paths = ["node_modules", ".venv", "dist", "build"]
 [reports]
 directory = ".ai/reports"
 logs_directory = ".ai/logs"
+
+[execution]
+mode = "enforce"
+maximum_impact = "high"
+allow_prefixes = ["python -m pytest", "python -m ruff", "python -m mypy"]
+deny_prefixes = ["git reset", "git clean"]
 ```
 
 Configuration takes precedence over auto detection. Invalid or unknown configuration is reported through `config_warnings` instead of crashing normal scans.
@@ -212,16 +284,29 @@ git diff --check
 | check | implemented |
 | check --explain | implemented |
 | test affected | implemented |
+| test flaky / check --retry-flaky | implemented |
 | index status/update/rebuild | implemented |
-| cache status/prune/clear | implemented |
+| index daemon | implemented |
+| plan / MCP plan_work | implemented |
+| semantic status/index | implemented with built-in Tree-sitter, LSP, and provider plugins |
+| policy assess / execution enforcement | implemented |
+| sarif | implemented |
+| cache status/prune/clear/layout | implemented |
 | logs summarize | implemented |
 | context build | implemented |
 | diagnostics | implemented |
+| mcp serve | implemented |
+| watch | implemented |
+| benchmark run/compare/gate/corpus | implemented |
+| integrations install | implemented for Codex, Claude Code, Cursor, and generic MCP |
+| dashboard status/serve | implemented, loopback-only |
+| performance latest/compare | implemented |
 | capabilities | implemented |
 | git status | implemented |
 | git inspect | implemented |
 | finish | implemented |
 | bootstrap | implemented |
+| environment explain | implemented |
 | run | implemented |
 | stop | implemented |
 
@@ -229,12 +314,12 @@ git diff --check
 
 - Monorepo/workspace detection and per-subproject command routing: implemented.
 - Per-subproject check and bootstrap working directories: implemented.
-- Runtime version validation: partial.
+- Runtime requirement detection and version validation: implemented.
 - `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.
+- Auto-commit, auto-push, destructive cleanup, remote source transmission, and GUI are intentionally out of scope.
 
 ## 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.
+Version 1.0.0 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.