ai-dev-cli-tools 1.1.0__tar.gz → 1.2.2__tar.gz

ai_dev_cli_tools-1.2.2/.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5
+  - package-ecosystem: github-actions
+    directory: "/"
+    schedule:
+      interval: weekly
+    open-pull-requests-limit: 5

{ai_dev_cli_tools-1.1.0 → ai_dev_cli_tools-1.2.2}/.github/workflows/ci.yml

@@ -5,12 +5,23 @@ on:
   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"]
+        python-version: ["3.11", "3.12", "3.13", "3.14"]
     runs-on: ${{ matrix.os }}
     steps:
       - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6

ai_dev_cli_tools-1.2.2/.github/workflows/codeql.yml

@@ -0,0 +1,28 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  schedule:
+    - cron: "17 4 * * 1"
+
+permissions:
+  contents: read
+  security-events: write
+
+jobs:
+  analyze:
+    name: Analyze Python
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: github/codeql-action/init@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
+        with:
+          languages: python
+          build-mode: none
+          queries: security-extended
+      - uses: github/codeql-action/analyze@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4

{ai_dev_cli_tools-1.1.0 → ai_dev_cli_tools-1.2.2}/.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.1.0 → ai_dev_cli_tools-1.2.2}/CHANGELOG.md

@@ -1,5 +1,72 @@
 # Changelog
 
+## Unreleased
+
+## 1.2.2 - 2026-09-08
+
+- Add a native Gemini CLI MCP integration, reference-first client profile, provider-reported
+  `usageMetadata` import, and Gemini pricing snapshot support.
+- Add Python 3.14 to the supported classifiers and cross-platform CI matrix.
+- Ignore named virtual environments and bytecode during changed-check selection, prefer the
+  project virtual-environment interpreter, and keep Ruff failures out of pytest-focused reruns.
+- Add CodeQL analysis, Dependabot update configuration, and a complete security reporting and
+  supported-version policy.
+- Make managed-process stop observe in-flight atomic supervisor state, closing a rare start/stop
+  race exposed by the expanded Python CI matrix.
+
+## 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

ai_dev_cli_tools-1.2.2/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.1.0 → ai_dev_cli_tools-1.2.2}/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.1.0 → ai_dev_cli_tools-1.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ai-dev-cli-tools
-Version: 1.1.0
+Version: 1.2.2
 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
@@ -17,6 +17,7 @@ Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Quality Assurance
 Requires-Python: >=3.11
 Requires-Dist: watchdog<7,>=4
@@ -57,7 +58,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.2
 ai-dev --help
 ```
 
@@ -67,9 +68,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
@@ -98,6 +103,7 @@ 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
@@ -113,10 +119,21 @@ 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 integrations install gemini
 ai-dev dashboard serve --port 8765
+ai-dev telemetry import response.json --client codex --format openai
+ai-dev telemetry import gemini-response.json --client gemini --format gemini
+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
@@ -139,9 +156,11 @@ All commands support `--project`, `--json`, `--quiet`, `--help`, and `--version`
 ## 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
+and progressive evidence as local structured tools for clients including Gemini CLI. 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
@@ -188,6 +207,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
 ```
@@ -196,7 +216,39 @@ Artifacts are written to `.ai/context/context-latest.md` and `.ai/context/contex
 
 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.
+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, Anthropic, or Gemini 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, Gemini CLI, 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
@@ -212,7 +264,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`.
@@ -288,6 +340,7 @@ git diff --check
 | 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 |
@@ -298,8 +351,12 @@ git diff --check
 | mcp serve | implemented |
 | watch | implemented |
 | benchmark run/compare/gate/corpus | implemented |
-| integrations install | implemented for Codex, Claude Code, Cursor, and generic MCP |
+| integrations install | implemented for Codex, Claude Code, Cursor, Gemini CLI, 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 |
@@ -312,6 +369,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.
@@ -320,6 +381,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.

{ai_dev_cli_tools-1.1.0 → ai_dev_cli_tools-1.2.2}/README.md

@@ -23,7 +23,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.2
 ai-dev --help
 ```
 
@@ -33,9 +33,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
@@ -64,6 +68,7 @@ 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
@@ -79,10 +84,21 @@ 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 integrations install gemini
 ai-dev dashboard serve --port 8765
+ai-dev telemetry import response.json --client codex --format openai
+ai-dev telemetry import gemini-response.json --client gemini --format gemini
+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
@@ -105,9 +121,11 @@ All commands support `--project`, `--json`, `--quiet`, `--help`, and `--version`
 ## 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
+and progressive evidence as local structured tools for clients including Gemini CLI. 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
@@ -154,6 +172,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
 ```
@@ -162,7 +181,39 @@ Artifacts are written to `.ai/context/context-latest.md` and `.ai/context/contex
 
 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.
+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, Anthropic, or Gemini 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, Gemini CLI, 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
@@ -178,7 +229,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`.
@@ -254,6 +305,7 @@ git diff --check
 | 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 |
@@ -264,8 +316,12 @@ git diff --check
 | mcp serve | implemented |
 | watch | implemented |
 | benchmark run/compare/gate/corpus | implemented |
-| integrations install | implemented for Codex, Claude Code, Cursor, and generic MCP |
+| integrations install | implemented for Codex, Claude Code, Cursor, Gemini CLI, 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 |
@@ -278,6 +334,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.
@@ -286,6 +346,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.

ai_dev_cli_tools-1.2.2/SECURITY.md

@@ -0,0 +1,36 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes are provided for the latest stable release only. Users should upgrade to the
+latest patch version before reporting an issue that may already be fixed. Pre-releases and source
+checkouts are supported only for reproducing a report against the current `main` branch.
+
+| Version | Supported |
+| --- | --- |
+| 1.2.x latest patch | Yes |
+| Earlier releases | No |
+
+## Reporting a vulnerability
+
+Do not open a public issue for a suspected vulnerability. Use GitHub's private vulnerability
+reporting form in the repository Security tab when available, or contact the repository owner
+privately through the address associated with the published package.
+
+Include the affected version or commit, operating system, minimal reproduction, expected security
+property, observed impact, and whether the report contains secrets. Do not include real
+credentials, private source code, or customer data. Use synthetic evidence wherever possible.
+
+The maintainer aims to acknowledge a report within 7 days and provide an initial assessment within
+14 days. Timelines for a fix and coordinated disclosure depend on severity and reproducibility.
+
+## Security boundaries
+
+`ai-dev` analyzes repositories and runs explicitly selected local development commands. Reports,
+caches, telemetry, and MCP communication remain local by default. The project intentionally does
+not commit, push, merge, deploy, transmit source to a remote model, install global tools, or kill
+unrelated processes.
+
+Secret masking is a defense-in-depth control, not permission to process arbitrary secrets. Review
+generated reports before sharing them, keep `.ai/` state private, and use least-privilege execution
+policies for MCP clients and CI.

{ai_dev_cli_tools-1.1.0 → ai_dev_cli_tools-1.2.2}/TODO.md

@@ -9,8 +9,10 @@ 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.
+There are no known incomplete P1 or P2 implementation items for the 1.0-1.2 contracts. The planned
+product capability set is complete. New work is maintenance and must be justified by a supported
+platform change, security issue, dependency update, reproducible regression, or backward-compatible
+integration requirement.
 
 ## Deferred or explicitly out of scope
 

{ai_dev_cli_tools-1.1.0 → ai_dev_cli_tools-1.2.2}/ai.ps1

@@ -3,5 +3,5 @@ param(
     [string[]]$Args
 )
 
-python -m ai_dev_tools.cli @Args
+python scripts/dev.py @Args
 exit $LASTEXITCODE

ai_dev_cli_tools-1.2.2/ai.sh

@@ -0,0 +1,3 @@
+#!/usr/bin/env sh
+set -eu
+python scripts/dev.py "$@"

{ai_dev_cli_tools-1.1.0 → ai_dev_cli_tools-1.2.2}/docs/AGENT_EFFICIENCY_ROADMAP.md

@@ -46,6 +46,10 @@ and longer-term direction without presenting proposed interfaces as available co
 | 24 | Optional semantic providers | Implemented | A bounded local structural index is built in; explicitly selected entry-point providers can add Tree-sitter or LSP-backed semantics, while auto mode fails closed to structural parsing. |
 | 25 | Execution policy | Implemented | Audit/enforce modes, allow/deny prefixes, impact ceilings, preview assessment, and enforcement cover checks, bootstrap, and managed application startup. |
 | 26 | CI-native agent evidence | Implemented | Reports convert deterministically to SARIF and the pinned GitHub Actions workflow publishes a compact plan summary plus code-scanning evidence. |
+| 27 | Adaptive context engine | Implemented | Task intent and local scope signals derive conservative token ceilings, explicit limits win, task-scoped incremental memory prevents cross-task omission, and the release corpus requires a measured token reduction without recall loss. |
+| 28 | Session delta feedback | Implemented | A client-acknowledged identical success is replaced by a fingerprinted validation/context receipt with exact expansion handles; missing acknowledgement, changed content, semantic validation changes, failures, warnings, and explicit opt-out preserve the full live payload. |
+| 29 | Evidence-based token optimizer | Implemented | Bounded p50/p95 attribution proposes token ceilings and cheaper models only after local quality and cost evidence meets explicit thresholds. |
+| 30 | Closed optimization loop | Implemented | Provider duration, daily trends, content-free JSON/CSV export, and correctness-gated benchmark decisions advise adopt, keep, or rollback while never mutating model policy automatically. |
 
 ## Implemented supporting capabilities
 
@@ -62,7 +66,7 @@ The current foundation also includes:
 
 ## Active direction
 
-The 1.0 capability set is complete. Further development should prioritize measured correctness,
+The planned 1.0-1.2 capability set is complete. Further development is maintenance and should prioritize measured correctness,
 backward-compatible schema evolution, parser fixtures for newly supported tool versions, and
 cross-platform performance evidence rather than adding overlapping commands.