ai-dev-cli-tools 1.0.0__tar.gz → 1.2.1__tar.gz

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

@@ -0,0 +1,131 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  launcher-smoke:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - run: python scripts/dev.py --diagnose
+      - run: python scripts/dev.py --bootstrap-only
+      - run: python scripts/dev.py --no-bootstrap --version
+
+  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-1.0.0 → ai_dev_cli_tools-1.2.1}/.github/workflows/docs.yml

@@ -8,8 +8,8 @@ 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 -c requirements-dev.lock -e ".[dev]"

{ai_dev_cli_tools-1.0.0 → ai_dev_cli_tools-1.2.1}/.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-1.0.0 → ai_dev_cli_tools-1.2.1}/.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/
@@ -88,17 +88,16 @@ jobs:
         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
-          --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-1.0.0 → ai_dev_cli_tools-1.2.1}/.gitignore

@@ -6,6 +6,7 @@
 .ai/logs/
 .ai/performance/
 .ai/reports/
+.ai/token-efficiency/
 .ai/release-venv/
 .coverage
 .mypy_cache/

{ai_dev_cli_tools-1.0.0 → ai_dev_cli_tools-1.2.1}/CHANGELOG.md

@@ -1,5 +1,82 @@
 # Changelog
 
+## Unreleased
+
+## 1.2.1 - 2026-09-01
+
+- Fix the blank local dashboard by preserving JavaScript newline escapes and resolving dashboard
+  containers explicitly instead of relying on browser-created globals.
+- Show a visible status card when the API request or response fails, tolerate partial status
+  payloads, and render all dynamic dashboard values through safe text nodes.
+
+## 1.2.0 - 2026-09-01
+
+- Complete the measured optimization loop with bounded latency samples, daily trends, aggregated
+  JSON/CSV export, and explicit human-approved adopt/keep/rollback benchmark decisions.
+- Harden managed-process startup with an observable starting/failed handshake, unique retry
+  identities, bounded child-spawn backoff, and preserved masked failure diagnostics.
+- Declare the planned product capability set complete and move the repository to compatibility,
+  security, dependency, platform, and regression maintenance.
+
+- Add an evidence-based, read-only token optimizer with p50/p95 attribution, safe budget
+  recommendations, and accuracy-first cheaper-model routing suggestions.
+- Allow provider usage records to include bounded phase, tool, task-kind, and boolean quality
+  evidence without storing prompts or responses.
+- Add telemetry budgets scoped globally, per client, and per model; equal-window regression gates;
+  immediate MCP/CLI alerts; chronological session windows; and integrity-checked, versioned pricing
+  snapshots with explicit activation and cost provenance.
+- Add bounded OpenAI, Anthropic, and generic provider-usage adapters, MCP `record_usage`,
+  idempotent JSON/JSONL imports, optional project-local pricing estimates, and per-client usage
+  totals in the CLI and loopback dashboard without storing model input or output content.
+- Add one-shot `ai-dev task` and MCP `prepare_task` workflows that combine a bounded plan,
+  context references, validation preview, per-client acknowledgement state, and a measurable token
+  savings receipt; full file content is now an explicit opt-in on this path.
+- Generate token-efficient Codex, Claude Code, Cursor, and generic client profiles, expose receipt
+  totals in the local dashboard, and optionally require provider-reported tokens in benchmark gates.
+- Make performance snapshot filenames collision-resistant on coarse-resolution clocks so rapid
+  measurements remain immutable and compare against the intended baseline.
+- Launch detached runtime supervisors through an isolated absolute-path bootstrap and preserve
+  bounded supervisor startup diagnostics instead of discarding early process failures.
+- Add a cross-platform developer launcher with locked `.venv` bootstrapping, isolated quality gates,
+  workspace-local temp routing, and machine-readable Git/ACL/proxy diagnostics.
+- Give detached runtime supervisors an absolute package import path so changing their working
+  directory cannot invalidate editable installs or relative `PYTHONPATH` entries.
+- Bind managed-process startup and stop acknowledgements to the current control token, tolerate
+  slow CI startup handshakes, and release Windows project handles before publishing terminal state.
+- Document the repository's required squash-merge workflow and post-merge `main` verification.
+- Make benchmark corpus and comparison evidence IDs resolvable through `ai-dev explain`.
+- Make index-daemon state writes resilient to transient Windows sharing violations and count
+  repository updates only when the indexed content fingerprint actually changes.
+- Add explicit MCP `build_context` acknowledgements: clients can return `acknowledged_state` to
+  receive a compact unchanged-context receipt, while changed, partial, or unsafe states retain
+  the full live payload. `delta=false` always requests full context.
+- Add deterministic adaptive context budgets and task-scoped incremental memory for agent turns.
+- Require a configurable minimum token reduction in A/B release corpus gates.
+- Add client-acknowledged feedback deltas that replace repeated successful validation and context
+  with fingerprinted receipts while retaining failures and warnings live.
+
+## 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.

ai_dev_cli_tools-1.2.1/CONTRIBUTING.md

@@ -0,0 +1,44 @@
+# Contributing
+
+Keep changes small, typed, tested, and conservative. Runtime code should avoid platform-specific assumptions and prefer `pathlib` for paths.
+
+From a fresh checkout, one cross-platform command creates or refreshes the locked `.venv` and runs
+every required gate without loading user-site packages:
+
+```bash
+python scripts/dev.py --check
+```
+
+Use `python scripts/dev.py --diagnose` to classify Python, workspace-temp, Git-metadata, and proxy
+problems without installing anything. `DEV_GIT_METADATA` means the host or sandbox must grant write
+access to `.git`; it is distinct from an existing-ref collision. `DEV_WORKSPACE_TEMP` means process
+tests cannot safely use the project-local temp directory in the current execution environment.
+
+The equivalent individual commands, when already inside the locked `.venv`, are:
+
+```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
+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.
+
+## Pull requests
+
+Keep each pull request focused and wait for the complete Linux, Windows, and macOS CI matrix.
+The repository does not allow merge commits. After required checks pass, maintainers should use a
+squash merge so `main` receives one descriptive commit, then delete the merged topic branch:
+
+```bash
+gh pr merge <number> --squash --delete-branch
+```
+
+Do not retry a rejected `--merge` operation or force-push `main`. Refresh the pull request state
+before merging and verify the resulting squash commit's `main` CI run.

{ai_dev_cli_tools-1.0.0 → ai_dev_cli_tools-1.2.1}/Makefile

@@ -1,4 +1,7 @@
-.PHONY: test lint typecheck coverage build
+.PHONY: check test lint typecheck coverage build
+
+check:
+	python scripts/dev.py --check
 
 test:
 	python -m pytest

{ai_dev_cli_tools-1.0.0 → ai_dev_cli_tools-1.2.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ai-dev-cli-tools
-Version: 1.0.0
+Version: 1.2.1
 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
@@ -19,12 +19,15 @@ 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
@@ -54,7 +57,7 @@ be safe for `ai-dev` to recreate.
 
 ```bash
 python -m pip install --upgrade pipx
-pipx install ai-dev-cli-tools==1.0.0
+pipx install ai-dev-cli-tools==1.2.1
 ai-dev --help
 ```
 
@@ -64,9 +67,13 @@ and upgrade policy.
 For development:
 
 ```bash
-python -m pip install -c requirements-dev.lock -e ".[dev]"
+python scripts/dev.py --check
 ```
 
+This creates a locked, repository-local `.venv`, disables ambient user-site packages, and routes
+temporary validation files through `.ai/tmp/dev`. Run `python scripts/dev.py --diagnose` for
+machine-readable Git metadata, temp-directory, Python, and proxy diagnostics without installation.
+
 ## Windows
 
 ```powershell
@@ -93,15 +100,37 @@ 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 task --task "implement rate limiting" --client codex --json
 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 telemetry import response.json --client codex --format openai
+ai-dev telemetry status --json
+ai-dev telemetry optimize --min-sessions 5 --json
+ai-dev telemetry export --format csv --output .ai/telemetry-exports/usage.csv --json
+ai-dev telemetry gate --json
+ai-dev telemetry pricing import pricing.json --provider openai --version 2026-09-01
+ai-dev telemetry pricing activate openai 2026-09-01
 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 feedback --task "fix authentication timeout" --ack-state <state-fingerprint>
+ai-dev feedback --task "fix authentication timeout" --no-delta  # force the full payload
 ai-dev watch --mode changed --debounce 500
 ai-dev session status
 ai-dev bootstrap --if-needed
@@ -123,10 +152,12 @@ All commands support `--project`, `--json`, `--quiet`, `--help`, and `--version`
 
 ## Local MCP server
 
-`ai-dev mcp serve` exposes project status, compact feedback, bounded context, validation,
+`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.
+defaults validation to preview-only. After consuming a successful `build_context` response, a
+client can return its `summary.delta.state_fingerprint` as `acknowledged_state`; an identical safe
+state then becomes a compact receipt, while changed or unsafe context remains live.
 
 ```bash
 codex mcp add ai-dev -- ai-dev --project "/absolute/path/to/project" mcp serve
@@ -135,6 +166,9 @@ 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.
@@ -170,6 +204,7 @@ ai-dev context build --retrieval auto --explain  # explains retrieval or abstent
 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 --adaptive  # task-aware budget; uncertainty expands, explicit limits win
 ai-dev context build --include "src/**/*.py" --exclude "tests/fixtures/**"
 ai-dev context build --explain --json
 ```
@@ -180,6 +215,38 @@ Selective retrieval defaults to `auto`: focused includes or changed files can ab
 
 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.
 
+`ai-dev task` is the default one-shot handoff for an AI client. It combines the bounded plan,
+selected context, and check preview while delivering file references instead of full content.
+Use `--include-content` only when the consumer truly needs the bodies. The response includes a
+state fingerprint and a token savings receipt; return that fingerprint with `--ack-state` only
+after consuming the response. Explicit acknowledgements are stored per client under
+`.ai/cache/client-state/`, so Codex, Claude Code, Cursor, and generic consumers never inherit one
+another's assumed context. Receipts remain local under `.ai/token-efficiency/`.
+
+Provider-reported usage can be recorded through MCP `record_usage` or imported from a bounded,
+project-local JSON/JSONL file with `ai-dev telemetry import`. OpenAI Responses, Anthropic, and a
+stable generic envelope for Cursor or other clients are normalized without retaining prompt or
+response content. `telemetry status` and the loopback dashboard aggregate input, cached input,
+output, and reasoning tokens by client. Optional cost values are local estimates computed from
+`.ai-dev/telemetry-pricing.json`; no changing provider price is hardcoded and no value is presented
+as a provider invoice. See `docs/INTEGRATIONS_AND_DASHBOARD.md`.
+Project-local `.ai-dev/telemetry-budgets.json` can enforce rolling aggregate limits globally,
+per client, and per model, and compare two chronological session windows for token or cost
+regressions. `ai-dev telemetry gate` returns a failing report for violations, while MCP
+`record_usage` immediately returns the active alerts and read-only `usage_status` provides a
+compact pre-flight check.
+
+`telemetry optimize` calculates deterministic p50/p95 usage, latency, cache share, cost, and
+quality attribution by client, model, phase, tool, task kind, and day. It recommends rolling token ceilings
+with an explicit safety margin. Cheaper-model recommendations appear only when both models have
+enough local quality samples, the candidate meets the configured accuracy target, complete
+same-currency cost evidence proves a saving, and the allowed accuracy drop is respected. It never
+switches a model or overwrites a policy. MCP clients can call the read-only `optimize_usage` tool
+for the same report.
+`telemetry export` writes only this aggregated evidence as JSON or CSV inside the project. It
+excludes request IDs, prompts, responses, and repository content and refuses to overwrite an
+existing file.
+
 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
@@ -194,7 +261,7 @@ Short reports are written to `.ai/reports/` as Markdown and JSON. Full command o
 
 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. 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`.
+`ai-dev feedback` combines Git changes, changed validation, adaptive incremental context, focused rerun hints, stage timings, and local session state into one compact agent protocol report. Adaptive context remains local and deterministic, scopes unchanged-file memory to a normalized task fingerprint, broadens uncertain requests, and never overrides explicit limits. A client may acknowledge the previous `delta.state_fingerprint` through `--ack-state`; only then can identical successful feedback become a small receipt. This prevents one AI client from inheriting another client's assumed context. Failures and warnings always remain live, and `--no-delta` forces the complete response. Its observation lifecycle replaces 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. 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`.
@@ -230,6 +297,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.
@@ -262,13 +335,25 @@ git diff --check
 | test affected | implemented |
 | test flaky / check --retry-flaky | implemented |
 | index status/update/rebuild | implemented |
+| index daemon | implemented |
+| plan / MCP plan_work | implemented |
+| task / MCP prepare_task | implemented with reference-first delivery and token receipts |
+| 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 | implemented |
+| benchmark run/compare/gate/corpus | implemented |
+| integrations install | implemented for Codex, Claude Code, Cursor, and generic MCP |
+| dashboard status/serve | implemented, loopback-only |
+| telemetry import/status and MCP record_usage | implemented, provider-reported usage only |
+| telemetry gate/pricing snapshots and MCP usage_status | implemented, local and fail-closed |
+| p50/p95 token optimizer and accuracy-first model recommendations | implemented, read-only |
+| aggregated telemetry export and latency trends | implemented, content-free |
 | performance latest/compare | implemented |
 | capabilities | implemented |
 | git status | implemented |
@@ -281,6 +366,10 @@ git diff --check
 
 ## Scope Notes
 
+The planned product capability set is complete as of 1.2.0. See
+[`docs/PROJECT_COMPLETE.md`](docs/PROJECT_COMPLETE.md) for the maintenance boundary and the exact
+acceptance evidence required for future changes.
+
 - Monorepo/workspace detection and per-subproject command routing: implemented.
 - Per-subproject check and bootstrap working directories: implemented.
 - Runtime requirement detection and version validation: implemented.
@@ -289,6 +378,6 @@ git diff --check
 - Auto-commit, auto-push, destructive cleanup, remote source transmission, and GUI are intentionally out of scope.
 
 ## Intentional Limits
-Version 1.0.0 does not reset, clean, commit, push, merge, clone organizations, synchronize repositories, delete containers, publish releases, or remove user files.
+Version 1.2.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.