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

{ai_dev_cli_tools-0.5.0a1 → ai_dev_cli_tools-1.0.0}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
         with:
           python-version: ${{ matrix.python-version }}
       - run: python -m pip install --upgrade pip
-      - run: python -m pip install -e ".[dev]"
+      - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
       - run: ruff check .
       - run: mypy src tests
       - run: coverage run -m pytest
@@ -63,7 +63,7 @@ jobs:
       - uses: gradle/actions/setup-gradle@v4
         with:
           gradle-version: "8.10"
-      - run: python -m pip install -e ".[dev]"
+      - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
       - name: Execute real fixture toolchains
         env:
           RUN_TOOLCHAIN_E2E: "1"

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

@@ -12,7 +12,7 @@ jobs:
       - uses: actions/setup-python@v5
         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.0.0}/.github/workflows/release.yml

@@ -84,6 +84,9 @@ 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
         with:
@@ -96,7 +99,6 @@ jobs:
           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 → ai_dev_cli_tools-1.0.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.0.0/CHANGELOG.md

@@ -0,0 +1,95 @@
+# Changelog
+
+## 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.0.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.0.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.0.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
@@ -25,6 +25,8 @@ 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: tokenizers
+Requires-Dist: tiktoken>=0.7; extra == 'tokenizers'
 Description-Content-Type: text/markdown
 
 # AI Dev CLI Tools
@@ -52,17 +54,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 +91,26 @@ 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 index update
 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 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 +121,24 @@ 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, 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 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 +161,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.
+
+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 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.
+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
 
@@ -212,16 +260,22 @@ 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 |
+| cache status/prune/clear/layout | implemented |
 | logs summarize | implemented |
 | context build | implemented |
 | diagnostics | implemented |
+| mcp serve | implemented |
+| watch | implemented |
+| benchmark run/compare | implemented |
+| 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 +283,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.

{ai_dev_cli_tools-0.5.0a1 → ai_dev_cli_tools-1.0.0}/README.md

@@ -23,17 +23,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
@@ -60,16 +60,26 @@ 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 index update
 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 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
@@ -80,6 +90,24 @@ 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, 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 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.
@@ -102,25 +130,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.
+
+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 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.
+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
 
@@ -183,16 +229,22 @@ 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 |
+| cache status/prune/clear/layout | implemented |
 | logs summarize | implemented |
 | context build | implemented |
 | diagnostics | implemented |
+| mcp serve | implemented |
+| watch | implemented |
+| benchmark run/compare | implemented |
+| performance latest/compare | implemented |
 | capabilities | implemented |
 | git status | implemented |
 | git inspect | implemented |
 | finish | implemented |
 | bootstrap | implemented |
+| environment explain | implemented |
 | run | implemented |
 | stop | implemented |
 
@@ -200,12 +252,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.

ai_dev_cli_tools-1.0.0/TODO.md

@@ -0,0 +1,24 @@
+# TODO
+
+This file contains only active implementation work. The 1.0 backlog was implemented and moved to
+`CHANGELOG.md`; product status and rationale are recorded in
+`docs/AGENT_EFFICIENCY_ROADMAP.md`.
+
+An item is complete only when implementation, tests, user documentation, report contracts, and
+cross-platform behavior are covered where applicable.
+
+## Active work
+
+There are no known incomplete P1 or P2 implementation items for the 1.0 contract. New work must be
+added here with tests, documentation, report-contract impact, and cross-platform acceptance criteria.
+
+## Deferred or explicitly out of scope
+
+The following require a separate design and safety review and must not be introduced implicitly:
+
+- automatic commit, push, merge, release, or deployment;
+- destructive Git cleanup or repository reset;
+- sending source code, logs, metrics, or secrets to a remote AI service;
+- killing arbitrary processes or deleting user-managed runtime data;
+- silently installing global tools or changing machine-level configuration;
+- learned/model-based semantic compression of code or verification evidence.

ai_dev_cli_tools-1.0.0/docs/ADAPTIVECHESSAI_FULL_CHECK_FAILURE_2026-08-30.md

@@ -0,0 +1,90 @@
+# `ai-dev check --mode full` failure for AdaptiveChessAI
+
+## Summary
+
+`ai-dev check --mode full --no-cache` returned a failed report for
+`AdaptiveChessAI` even though the root project checks completed successfully.
+The tool incorrectly detected the ignored virtual-environment copy of pandas as
+a second workspace and then crashed while printing its report on a CP1250
+console.
+
+## Environment
+
+- Date: 2026-08-30
+- OS: Windows
+- Console encoding: CP1250
+- Python selected by ai-dev: 3.14
+- ai-dev-cli-tools: 0.5.0a1
+- Project: `C:\Users\Praca\fork\MatthiasLew\AdaptiveChessAI`
+
+## Command
+
+```powershell
+ai-dev --project "C:\Users\Praca\fork\MatthiasLew\AdaptiveChessAI" `
+  check --mode full --no-cache
+```
+
+## Observed problems
+
+### 1. Ignored virtual environment detected as a workspace
+
+The plan contained two workspaces:
+
+```text
+<project root>
+venv/Lib/site-packages/pandas
+```
+
+The second path is an installed dependency inside the project's ignored
+`venv/` directory and must not be treated as a project workspace.
+
+This caused irrelevant checks to run against pandas, including Black, Ruff,
+mypy and pytest. The pandas pytest run failed because the virtual environment
+contains CPython 3.13 native NumPy extensions while ai-dev selected Python 3.14.
+
+### 2. Text reporter crashed on CP1250
+
+After creating the Markdown and JSON reports, the CLI crashed while printing a
+message containing the Unicode replacement character:
+
+```text
+UnicodeEncodeError: 'charmap' codec can't encode character '\ufffd'
+```
+
+The exception originated in `ai_dev_tools.cli._print_text`.
+
+### 3. Misleading aggregate result
+
+The root-project pytest check passed 271 tests and the root mypy check passed,
+but failures from the incorrectly detected pandas workspace made the aggregate
+command fail. Some structured result entries also contained a non-zero
+`exit_code` together with `status: success`, which makes the report harder to
+interpret reliably.
+
+## Expected behavior
+
+- Directories ignored as virtual environments (`venv`, `.venv`, `env`) should
+  be excluded from workspace discovery.
+- Output should be encoded safely on Windows consoles, for example by replacing
+  unsupported characters or explicitly using UTF-8.
+- A subprocess with a non-zero exit code should not be represented as a
+  successful check result.
+
+## Resolution
+
+The unreleased implementation now excludes `env` and `venv` trees from workspace discovery,
+replaces characters unsupported by the active text-console encoding, and passes subprocess exit
+codes into result parsing so a non-zero result cannot be serialized as successful. Regression tests
+cover all three cases.
+
+## Artifacts
+
+The failing run created local evidence under the inspected repository:
+
+```text
+.ai/reports/check-full-latest.json
+.ai/reports/check-full-latest.md
+.ai/logs/check-20260830-1844*.log
+```
+
+The `.ai/` directory is ignored by Git.