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

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

@@ -5,6 +5,17 @@ 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

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

@@ -1,5 +1,60 @@
 # 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

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.1.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.1.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.1.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
@@ -57,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
 ```
 
@@ -67,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
@@ -98,6 +102,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
@@ -114,9 +119,18 @@ ai-dev benchmark run --suite examples/benchmarks/output-budget-smoke.json --vari
 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
@@ -141,7 +155,9 @@ All commands support `--project`, `--json`, `--quiet`, `--help`, and `--version`
 `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
@@ -188,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
 ```
@@ -198,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
@@ -212,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`.
@@ -288,6 +337,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 |
@@ -300,6 +350,10 @@ git diff --check
 | 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 |
@@ -312,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.
@@ -320,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.

{ai_dev_cli_tools-1.1.0 → ai_dev_cli_tools-1.2.1}/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.1
 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
@@ -80,9 +85,18 @@ ai-dev benchmark run --suite examples/benchmarks/output-budget-smoke.json --vari
 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
@@ -107,7 +121,9 @@ All commands support `--project`, `--json`, `--quiet`, `--help`, and `--version`
 `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
@@ -154,6 +170,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
 ```
@@ -164,6 +181,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
@@ -178,7 +227,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 +303,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 |
@@ -266,6 +316,10 @@ git diff --check
 | 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 |
@@ -278,6 +332,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 +344,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.1}/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.1}/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.1/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.1}/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.
 

ai_dev_cli_tools-1.2.1/docs/AGENT_INTEGRATION_CONTRACT.md

@@ -0,0 +1,79 @@
+# Coding Agent Integration Contract
+
+The supported integration surfaces are the `ai-dev` command line, report schema `1.1`, and the
+local `ai-dev mcp serve` STDIO server.
+Integrations must request JSON with `--json` and must not parse Markdown or terminal prose.
+
+## Stability
+
+- `schema_version`, `command`, `status`, `exit_code`, `summary`, `issues`, `artifacts`, and
+  `metadata` are stable top-level fields for schema 1.x.
+- Consumers must ignore unknown fields and tolerate new enum values.
+- Paths are native absolute paths in artifacts and project-relative paths in repository data.
+- `success`, `partial`, and `warning` are non-error CLI outcomes; other statuses return nonzero.
+- Breaking removals or type changes require a schema-major change.
+
+## Recommended loop
+
+1. Prefer MCP `prepare_task` or `ai-dev task --task "<task>" --client <client> --json` for a
+   single bounded handoff. Use `plan_work` alone only when context selection is not yet needed.
+2. Run `ai-dev cache layout --json` once per content state and place stable sections before task-specific content at the recommended breakpoint.
+3. Prefer `ai-dev feedback --task "<task>" --json` for the normal compact loop.
+4. Inspect `decision`, `changes`, `validation`, `context`, `observations`, `delta`, and `performance`.
+   Pass the prior `delta.state_fingerprint` as `--ack-state` (or MCP `acknowledged_state`) only
+   after consuming that response. When `delta.reused=true`, expand only the evidence required for
+   the next decision. Use `--no-delta` when a consumer explicitly requires the repeated payload.
+5. Use `ai-dev session status --json` after an interrupted handoff.
+6. Read `metadata.progressive.references` and expand only the evidence needed.
+7. Use failure signatures to deduplicate retries and optionally compare a named local baseline.
+8. Treat flaky passes, low confidence, and recall regressions as unresolved evidence.
+9. Before handoff, run `ai-dev finish --json` and a complete validation pass.
+10. When the provider exposes numeric usage, call MCP `record_usage` once after the response.
+    Send total input, cache read/write, output and reasoning counts, client, and optional
+    model/request ID and optional bounded phase/tool/task-kind labels plus a boolean quality
+    outcome; never send prompt or response text. Treat `measurement=provider_reported` as the
+    provenance of counts and any
+    `cost.kind=local_pricing_estimate` as an estimate, not billed cost.
+11. Read `summary.policy` returned by `record_usage`. Stop additional expensive work on active
+    violations unless the user explicitly changes the budget. Use read-only `usage_status` before
+    a costly phase and `ai-dev telemetry gate --json` in deterministic CI/release gates.
+12. Call read-only `optimize_usage` after enough representative sessions. Treat budget output as
+    a proposal, never permission to overwrite policy. Never switch to a cheaper model unless the
+    recommendation includes sufficient quality samples, meets the accuracy target, proves a
+    same-currency saving, and a human or owning agent approves the change.
+
+All acceleration state is local under `.ai/`; no command transmits repository contents or
+metrics.
+
+## MCP integration
+
+Use the local MCP server when the agent supports structured tools. Tool results contain concise
+text and machine-readable `structuredContent`; consumers should prefer the structured data.
+
+- Call `project_status`, then `plan_work`, before broad repository work.
+- Prefer `prepare_task` when one compact call should replace separate planning, context, and check
+  discovery calls. File bodies are references by default; request `include_content=true` only on
+  demand.
+- Use `feedback`, `build_context`, and `run_checks` in their preview-only defaults.
+- Set execution or artifact-writing flags only when the task requires them.
+- Expand one stable ID with `explain_evidence` instead of requesting full logs.
+- Treat tool names and required fields as compatibility contracts.
+- Ignore new optional fields and new tools.
+- Use `record_usage` only with usage returned by the provider. Do not substitute tokenizer or
+  character estimates, because estimated context savings and provider-reported consumption are
+  separate measurements.
+- Treat `TELEMETRY_REGRESSION_INSUFFICIENT_DATA` as informational. Treat budget, cost-data, and
+  regression violations as unresolved until the policy or measured workload changes.
+- Treat every `MODEL_ROUTING_*` gap as evidence that routing must remain unchanged. A
+  `MODEL_ROUTING_RECOMMENDATION` is advisory and never grants permission to mutate client config.
+- Respect MCP annotations and the configured client approval policy.
+
+For repeated `build_context` calls, return the prior `summary.delta.state_fingerprint` as
+`acknowledged_state`. A receipt is emitted only when repository contents, request parameters, and
+the safe successful state still match. Changed, partial, warning, error, and secret-bearing states
+return full live context. Set `delta=false` whenever a complete refresh is required.
+- `prepare_task` accepts `client=codex|claude|cursor|generic`. Persisted acknowledgement state is
+  updated only when the caller explicitly supplies `acknowledged_state` with `persist_ack=true`.
+- Keep infrastructure retry separate from flaky-test retry; neither may retry code failures.
+
+See `MCP_SERVER.md` for setup and complete safety boundaries.

{ai_dev_cli_tools-1.1.0 → ai_dev_cli_tools-1.2.1}/docs/BENCHMARKS.md

@@ -35,8 +35,14 @@ ai-dev benchmark run --suite benchmarks/agent-workflows.json --variant ai-dev --
 ai-dev benchmark compare .ai/benchmarks/runs/<baseline>.json .ai/benchmarks/runs/<candidate>.json
 ai-dev benchmark gate .ai/benchmarks/runs/<baseline>.json .ai/benchmarks/runs/<candidate>.json
 ai-dev benchmark corpus --manifest examples/benchmarks/agent-corpus.json --trials 3
+ai-dev benchmark run --suite benchmarks/real-codex.json --variant ai-dev --client codex --trials 5
+ai-dev benchmark gate <baseline.json> <candidate.json> --require-reported-tokens
 ~~~
 
+The corpus includes a repeated MCP `build_context` task that compares a forced full refresh with
+an explicitly acknowledged unchanged receipt. Both variants must retain the same outcome,
+precision, and recall while the receipt satisfies the configured token-reduction threshold.
+
 Cold and warm results are deliberately separate and cannot be compared with each other. A
 comparison is valid only when the suite name, fixture version, cache state, and validated outcome
 signatures match and every trial succeeds.
@@ -48,8 +54,11 @@ masked_utf8_bytes_divided_by_4; they are a stable approximation, not a model tok
 Raw JSON and compact Markdown reports stay under `.ai/benchmarks/`.
 
 `benchmark gate` fails when correctness differs, candidate time or token regressions exceed their
-bounds, precision/recall fall below their floors, or false negatives exceed the allowance. The
-versioned corpus runs all four representative agent tasks and applies the shared thresholds from
+bounds, required token reduction is not achieved, precision/recall fall below their floors, or false negatives exceed the allowance. Use
+`--min-token-reduction PERCENT` to require a measured improvement rather than merely permitting no
+regression. The
+versioned corpus runs six representative agent tasks, including adaptive-off versus adaptive-on
+context selection and full versus session-delta feedback, and applies the shared thresholds from
 `examples/benchmarks/agent-corpus.json`; it is suitable as a CI release gate.
 
 A suite variant may emit one private `AI_DEV_BENCHMARK_METRICS=` JSON line on stderr to
@@ -63,6 +72,17 @@ agent-visible bytes. Missing or invalid metrics safely fall back to generic meas
 never presented as exact model-token counts. `selection_metric_trials` is zero when precision and
 recall were not reported; their zero medians must not be interpreted as measured selection quality.
 
+Use `--client codex|claude|cursor|generic` to label runs from a real client adapter. A real adapter
+should emit `input_tokens` or `output_tokens` in its private metrics line. The
+`--require-reported-tokens` gate fails unless every candidate trial contains provider-reported
+usage; this prevents estimated character counts from being presented as real client token data.
+
+Every comparison and gate is advisory and requires human approval. A passing candidate that is
+both faster and smaller returns `adopt_candidate`; a passing tradeoff returns `keep_baseline`; any
+correctness, recall, token, time, or reported-usage gate failure returns `rollback_candidate`.
+Reports always set `automatic_rollback: false`, so an agent cannot reinterpret the evidence as
+permission to change model or client configuration.
+
 ## Included suites
 
 `examples/benchmarks/mcp-recurring-status.json` compares recurring project status collection.