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

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

@@ -0,0 +1,120 @@
+name: CI
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest, macos-latest]
+        python-version: ["3.11", "3.12", "3.13"]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: python -m pip install --upgrade pip
+      - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
+      - run: ruff check .
+      - run: mypy src tests
+      - run: coverage run -m pytest
+      - run: coverage report --fail-under=90
+      - run: python -m build
+      - run: python scripts/test_installed_package.py
+      - run: python scripts/validate_ci.py
+      - run: ai-dev --version
+      - run: ai-dev doctor --json
+      - run: ai-dev scan --json
+      - run: ai-dev bootstrap --explain --json
+      - run: ai-dev capabilities --json
+      - run: ai-dev context build --explain --json
+      - run: ai-dev git inspect --json
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: ai-dev-reports-${{ matrix.os }}-${{ matrix.python-version }}
+          path: |
+            .ai/reports
+            .ai/logs
+          if-no-files-found: ignore
+  toolchain-e2e:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - uses: actions/setup-node@820762786026740c76f36085b0efc47a31fe5020 # v7.0.0
+        with:
+          node-version: "22"
+      - uses: actions/setup-java@dd06d9cba3e5552c54d9f8ea23572deb30010f7c # v6.0.0
+        with:
+          distribution: temurin
+          java-version: "17"
+      - uses: dtolnay/rust-toolchain@4360b52568e2003a75bf9bc1d59f33a8e3fc893c # stable 2026-08-31
+      - uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # 2.37.2
+        with:
+          php-version: "8.3"
+          tools: composer
+      - uses: gradle/actions/setup-gradle@9c971963bec38e04b3d30dcc455b5382be2fdbfb # v6.3.0
+        with:
+          gradle-version: "8.10"
+      - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
+      - name: Execute real fixture toolchains
+        env:
+          RUN_TOOLCHAIN_E2E: "1"
+          E2E_TOOLCHAINS: python,node,rust,maven,gradle,php
+        run: python -m pytest tests/integration/test_toolchain_e2e.py -q
+
+  agent-corpus:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
+      - name: Run real-agent regression corpus
+        run: >-
+          ai-dev benchmark corpus
+          --manifest examples/benchmarks/agent-corpus.json
+          --trials 3
+          --timeout 60
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        if: always()
+        with:
+          name: agent-corpus-results
+          path: .ai/benchmarks
+          if-no-files-found: error
+
+  agent-report:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      security-events: write
+    steps:
+      - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+      - uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6
+        with:
+          python-version: "3.13"
+      - run: python -m pip install -c requirements-dev.lock -e ".[dev]"
+      - name: Build bounded agent plan
+        run: ai-dev plan --task "Review this commit" --json
+      - name: Export SARIF
+        run: ai-dev sarif --input .ai/reports/agent-plan.json --output .ai/reports/ai-dev.sarif
+      - name: Add agent plan to job summary
+        run: cat .ai/reports/agent-plan.md >> "$GITHUB_STEP_SUMMARY"
+      - name: Upload SARIF to GitHub code scanning
+        if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
+        uses: github/codeql-action/upload-sarif@cdf488f595d80d6e07e03d4674febd5ab45fa938 # v4
+        with:
+          sarif_file: .ai/reports/ai-dev.sarif

{ai_dev_cli_tools-1.0.0 → ai_dev_cli_tools-1.1.0}/.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.1.0}/.github/workflows/publish-pypi.yml

@@ -10,6 +10,7 @@ permissions:
 
 jobs:
   validate-release:
+    if: github.event.release.prerelease == false
     name: Validate manually promoted release artifacts
     runs-on: ubuntu-latest
     steps:
@@ -36,7 +37,7 @@ jobs:
           python -m twine check dist/*
           python scripts/validate_release.py --tag "$RELEASE_TAG" --dist dist
       - name: Upload validated production artifact
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: pypi-distributions
           path: dist/
@@ -44,6 +45,7 @@ jobs:
           retention-days: 7
 
   publish-pypi:
+    if: github.event.release.prerelease == false
     name: Publish manually approved release to PyPI
     needs: validate-release
     runs-on: ubuntu-latest
@@ -54,7 +56,7 @@ jobs:
       id-token: write
     steps:
       - name: Download validated production artifact
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: pypi-distributions
           path: dist/
@@ -64,6 +66,7 @@ jobs:
           packages-dir: dist/
 
   verify-pypi:
+    if: github.event.release.prerelease == false
     name: Verify PyPI pipx installation
     needs: publish-pypi
     runs-on: ubuntu-latest

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

@@ -31,7 +31,7 @@ jobs:
           python scripts/validate_release.py --tag "$GITHUB_REF_NAME" --dist dist
           python scripts/test_installed_package.py
       - name: Upload immutable distribution artifact
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         with:
           name: python-package-distributions
           path: dist/
@@ -49,7 +49,7 @@ jobs:
       id-token: write
     steps:
       - name: Download distribution artifact
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: python-package-distributions
           path: dist/
@@ -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.1.0}/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.1.0 - 2026-08-31
+
+Stable promotion of `1.1.0rc1` after cross-platform CI, benchmark regression gates, and a clean
+TestPyPI installation smoke test.
+
+- Add `plan` and MCP `plan_work` for bounded, preview-only implementation plans with scope,
+  dependencies, validation, risk, policy assessments, and stable evidence references.
+- Add built-in Tree-sitter AST and LSP document-symbol backends alongside the local structural
+  fallback and semantic plugin contract.
+- Add a detached, localhost-authenticated index daemon using native filesystem events, IPC
+  start/status/stop control, lifecycle state, and no periodic repository rescans.
+- Classify command failures and retry only transient infrastructure failures while preserving the
+  first failure and recovery evidence.
+- Add configurable command allow/deny prefixes and impact limits, enforced by checks, bootstrap,
+  and application startup, plus a preview-only `policy assess` command.
+- Extend reproducible benchmarks with precision, recall, false negatives, iterations, files read,
+  reported token metrics, a versioned real-agent corpus, and enforceable regression gates.
+- Add ready project-scoped MCP configurations for Codex, Claude Code, Cursor, and generic clients.
+- Add a loopback-only local dashboard for index, semantic, cache, runtime, daemon, and error health.
+- Add deterministic report-to-SARIF conversion and a GitHub Actions code-scanning summary job.
+- Upgrade and SHA-pin supported GitHub Actions used by CI, docs, and publishing workflows.
+
 ## 1.0.0 - 2026-08-31
 
 - Stabilize the local CLI and report schema for the 1.0 release line.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ai-dev-cli-tools
-Version: 1.0.0
+Version: 1.1.0
 Summary: Cross-platform CLI helpers that give AI coding agents concise, deterministic development reports.
 Project-URL: Homepage, https://github.com/MatthiasLew/ai-dev-cli-tools
 Project-URL: Repository, https://github.com/MatthiasLew/ai-dev-cli-tools
@@ -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
@@ -93,12 +96,24 @@ ai-dev check --mode full --jobs 4
 ai-dev check --mode changed --policy feedback-first --resume
 ai-dev check --mode changed --compare main
 ai-dev check --mode changed --retry-flaky 1
+ai-dev check --mode changed --retry-infra 1
+ai-dev plan --task "implement rate limiting" --mode changed
 ai-dev index update
+ai-dev index daemon start
+ai-dev index daemon status
+ai-dev index daemon stop
+ai-dev semantic status
+ai-dev semantic index --backend auto
+ai-dev policy assess -- python -m pytest
+ai-dev sarif --input .ai/reports/agent-plan.json
 ai-dev cache status
 ai-dev cache layout
 ai-dev baseline create main
 ai-dev baseline compare main
 ai-dev benchmark run --suite examples/benchmarks/output-budget-smoke.json --variant baseline
+ai-dev benchmark corpus --manifest examples/benchmarks/agent-corpus.json --trials 3
+ai-dev integrations install all
+ai-dev dashboard serve --port 8765
 ai-dev explain issue:<id> --tail 100
 ai-dev explain --symbol "src/app.py#Application.run" --tail 100
 ai-dev feedback --task "fix authentication timeout"
@@ -123,7 +138,7 @@ 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.
@@ -135,6 +150,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.
@@ -230,6 +248,12 @@ paths = ["node_modules", ".venv", "dist", "build"]
 [reports]
 directory = ".ai/reports"
 logs_directory = ".ai/logs"
+
+[execution]
+mode = "enforce"
+maximum_impact = "high"
+allow_prefixes = ["python -m pytest", "python -m ruff", "python -m mypy"]
+deny_prefixes = ["git reset", "git clean"]
 ```
 
 Configuration takes precedence over auto detection. Invalid or unknown configuration is reported through `config_warnings` instead of crashing normal scans.
@@ -262,13 +286,20 @@ 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 |
+| 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 |
 | performance latest/compare | implemented |
 | capabilities | implemented |
 | git status | implemented |

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

@@ -62,12 +62,24 @@ ai-dev check --mode full --jobs 4
 ai-dev check --mode changed --policy feedback-first --resume
 ai-dev check --mode changed --compare main
 ai-dev check --mode changed --retry-flaky 1
+ai-dev check --mode changed --retry-infra 1
+ai-dev plan --task "implement rate limiting" --mode changed
 ai-dev index update
+ai-dev index daemon start
+ai-dev index daemon status
+ai-dev index daemon stop
+ai-dev semantic status
+ai-dev semantic index --backend auto
+ai-dev policy assess -- python -m pytest
+ai-dev sarif --input .ai/reports/agent-plan.json
 ai-dev cache status
 ai-dev cache layout
 ai-dev baseline create main
 ai-dev baseline compare main
 ai-dev benchmark run --suite examples/benchmarks/output-budget-smoke.json --variant baseline
+ai-dev benchmark corpus --manifest examples/benchmarks/agent-corpus.json --trials 3
+ai-dev integrations install all
+ai-dev dashboard serve --port 8765
 ai-dev explain issue:<id> --tail 100
 ai-dev explain --symbol "src/app.py#Application.run" --tail 100
 ai-dev feedback --task "fix authentication timeout"
@@ -92,7 +104,7 @@ 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.
@@ -104,6 +116,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.
@@ -199,6 +214,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.
@@ -231,13 +252,20 @@ 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 |
+| 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 |
 | performance latest/compare | implemented |
 | capabilities | implemented |
 | git status | implemented |

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

@@ -33,7 +33,7 @@ and longer-term direction without presenting proposed interfaces as available co
 | 11 | Compact agent protocol | Implemented | Schema 1.1 JSON reports, stable reason codes, evidence references, bounded output, and the local MCP server provide the supported machine contract. |
 | 12 | Local session state | Implemented | Versioned local session and observation state retains task, validation, context, and unresolved failure evidence without storing a conversation transcript. |
 | 13 | Dependency-aware parallel scheduler | Implemented | `check --jobs` respects explicit check dependencies, CPU/memory/exclusive resource classes, feedback-first gates, and deterministic report order. Failed dependencies conservatively cancel their dependents. |
-| 14 | Persistent repository index | Implemented | `index status/update/rebuild` maintains a schema-versioned, content-addressed index under `.ai/cache/`. |
+| 14 | Persistent repository index | Implemented | `index status/update/rebuild` maintains a schema-versioned, content-addressed index under `.ai/cache/`; foreground `index daemon` keeps it warm with bounded polling and lifecycle state. |
 | 15 | Watch mode | Implemented | Foreground polling, debounce, generated-root exclusion, queued changes, bounded runs, and cancellation of subprocesses owned by obsolete validations are implemented. Cancellation never targets an unrelated PID. |
 | 16 | Priority and fail-fast scheduling | Implemented | `feedback-first` and `complete` policies provide deterministic priority waves and required-failure gating. |
 | 17 | Warm environment state | Implemented | `bootstrap --if-needed` and `environment explain` reuse only revalidated executable, dependency, configuration, runtime, and plan fingerprints. |
@@ -41,7 +41,11 @@ and longer-term direction without presenting proposed interfaces as available co
 | 19 | Flaky-test awareness | Implemented | Opt-in bounded retries preserve first failures, exclude deterministic/environment failures, avoid caching flaky passes, and maintain bounded local history. |
 | 20 | Unified feedback command | Implemented | `feedback` composes Git changes, changed validation, incremental context, focused reruns, timings, observations, and session state. |
 | 21 | Performance budgets | Implemented | Schema-versioned local timing records, total/per-stage budgets, bounded retention, and `performance latest/compare` diagnostics are available. |
-| 22 | Reproducible workflow benchmarks | Implemented | Versioned local suites support repeated cold/warm trials, correctness gates, machine-readable results, and compact comparisons for repair, affected-test, multi-turn, and monorepo scenarios. |
+| 22 | Reproducible workflow benchmarks | Implemented | Versioned local suites support repeated cold/warm trials, correctness gates, precision/recall and false-negative metrics, token/iteration/file telemetry, machine-readable results, and compact comparisons. |
+| 23 | Agent execution plans | Implemented | `plan` and MCP `plan_work` emit preview-only scope, risk, dependencies, command-policy assessments, validation schedules, and stable evidence references. |
+| 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. |
 
 ## Implemented supporting capabilities
 

{ai_dev_cli_tools-1.0.0 → ai_dev_cli_tools-1.1.0}/docs/AGENT_INTEGRATION_CONTRACT.md

@@ -15,14 +15,15 @@ Integrations must request JSON with `--json` and must not parse Markdown or term
 
 ## Recommended loop
 
-1. Run `ai-dev cache layout --json` once per content state and place its stable sections before task-specific content at the recommended breakpoint.
-2. Prefer `ai-dev feedback --task "<task>" --json` for the normal compact loop.
-3. Inspect `decision`, `changes`, `validation`, `context`, `observations`, and `performance`.
-4. Use `ai-dev session status --json` after an interrupted handoff.
-5. Read `metadata.progressive.references` and call `ai-dev explain <evidence-id> --json` only for needed evidence.
-6. Use failure signatures to deduplicate retries and optionally compare a named local baseline.
-7. Treat FLAKY_PASS and checks_flaky as unresolved warning evidence; never report them as a clean first-pass success.
-8. Before handoff, run `ai-dev finish --json`.
+1. Call `plan_work` or run `ai-dev plan --task "<task>" --json` before broad edits.
+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`, `scope`, `changes`, `validation`, `context`, `observations`, and `performance`.
+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.
 
 All acceleration state is local under `.ai/`; no command transmits repository contents or
 metrics.
@@ -32,12 +33,13 @@ metrics.
 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` before planning broad repository work.
+- Call `project_status`, then `plan_work`, before broad repository work.
 - 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.
 - Respect MCP annotations and the configured client approval policy.
+- 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/docs/AGENT_WORKFLOW.md

@@ -0,0 +1,77 @@
+# Agent workflow
+
+The recommended loop gives an AI agent enough evidence to act without granting broad execution
+or forcing it to reread the repository.
+
+## 1. Plan before editing
+
+```bash
+ai-dev plan --task "fix authentication timeout" --mode changed --json
+```
+
+The plan is preview-only and caps scope at 30 files, 20 symbols, and 50 evidence rows. It reports
+intended scope, changed symbols, file risk, dependent actions,
+selected validation commands, command-policy decisions, and stable evidence references. It writes
+`.ai/reports/agent-plan.json` and `.ai/reports/agent-plan.md`. MCP clients should call
+`plan_work` for the same contract.
+
+## 2. Retrieve bounded context
+
+Use `context build --profile implement` for code changes and `--profile docs` for documentation.
+Prefer `--incremental`, task text, or explicit evidence IDs. Expand one uncertainty with
+`ai-dev explain <evidence-id>` instead of requesting a full tree or log.
+
+The optional semantic index is local and deterministic:
+
+```bash
+ai-dev semantic status
+ai-dev semantic index --backend auto
+```
+
+`auto` uses the built-in structural parser unless an explicitly supported provider is selected.
+Third-party providers register the `ai_dev_tools.semantic_backends` entry-point group and expose
+an `index(project_root, paths)` method returning bounded symbol objects. Provider code runs in the
+local process and therefore must be trusted like any development dependency.
+
+## 3. Assess commands before execution
+
+```bash
+ai-dev policy assess -- python -m pytest tests/unit -q --json
+```
+
+Configure `[execution]` in `.ai-dev-tools.toml`. `audit` reports decisions without blocking;
+`enforce` applies allow/deny prefixes and `maximum_impact` to checks, bootstrap, and application
+startup. Argument arrays are always executed without a shell. Policy does not turn an untrusted
+repository into a trusted one; review project configuration before running it.
+
+## 4. Validate narrowly, then completely
+
+```bash
+ai-dev check --mode changed --policy feedback-first --retry-infra 1 --json
+ai-dev check --mode full --jobs 4 --json
+```
+
+Only failures classified as transient infrastructure are retried automatically. Code,
+environment, policy, cancellation, and timeout failures are not hidden by retry. Recovered runs
+retain their initial output and attempt count. Flaky-test retry remains separate and opt-in through
+`--retry-flaky`.
+
+## 5. Publish compact evidence
+
+```bash
+ai-dev sarif --input .ai/reports/check-latest.json --output .ai/reports/ai-dev.sarif
+```
+
+SARIF conversion is project-scoped, secret-masked, capped at 10 MB input and 5,000 results, and
+does not contact GitHub. CI may upload the result to code scanning and place the readable plan in
+the job summary. Full logs remain local artifacts and should be opened only for a failed evidence
+reference.
+
+## Recommended agent defaults
+
+- Start with `project_status` or `plan_work`, not an unbounded repository read.
+- Keep execution preview-only until the user or client policy allows it.
+- Use `implement` or `docs` context profiles and stable evidence IDs.
+- Treat low confidence, truncation, and recall regressions as reasons to broaden validation.
+- Run a full validation pass before claiming completion.
+- Never infer permission to commit, push, merge, publish, deploy, or delete from these tools.

{ai_dev_cli_tools-1.0.0 → ai_dev_cli_tools-1.1.0}/docs/ARCHITECTURE.md

@@ -6,17 +6,23 @@
 
 - Detectors inspect environment and project structure without changing files.
 - Runners execute existing project commands with `subprocess.run(shell=False)`, timeouts, UTF-8 output, and full log capture.
-- Parsers reduce raw command output into first failure, project frame, repeated warning groups, and issue lists.
-- Reporters write stable Markdown and JSON reports.
+- Parsers reduce raw command output into first failure, project frame, repeated warning groups,
+  issue lists, and retry-safe failure classes.
+- Reporters write stable Markdown, JSON, and project-scoped SARIF reports.
 - Git helpers inspect repository state without destructive operations.
-- Security helpers scan changed files for masked secret findings.
+- Security helpers scan changed files for masked secret findings and assess command impact against
+  configurable execution policy.
 - Context builders compose detector, git, runner-plan, parser, and security outputs into bounded AI context packages.
 - The MCP adapter exposes bounded local reports as strict STDIO JSON-RPC tools without duplicating detector or runner logic.
+- The semantic adapter maintains a bounded structural symbol index and loads explicitly selected
+  trusted providers through `ai_dev_tools.semantic_backends`.
 - Packaging smoke tests build a wheel, install it into a clean virtual environment, and verify the installed `ai-dev` entrypoint.
 
 ## Data Flow
 
-CLI or MCP tool -> detector/runner/context builder -> full log or bounded source selection -> parser/security masking -> `Report` model -> Markdown/JSON artifacts or concise MCP `structuredContent`.
+CLI or MCP tool -> plan/detector/runner/context builder -> full log or bounded source selection ->
+parser/security classification and masking -> `Report` model -> Markdown/JSON/SARIF artifacts or
+concise MCP `structuredContent`.
 
 ## Extending
 
@@ -31,6 +37,10 @@ classes. CPU tasks consume one slot, memory-heavy tasks consume two, and exclusi
 alone. Results are always restored to deterministic plan order. Watch cancellation propagates an
 in-memory token only to subprocesses created by the active validation.
 
+Before execution, checks are assessed against the configured command policy. Failed commands are
+classified as code, environment, infrastructure, timeout, cancellation, policy, or unknown.
+Only transient infrastructure failures receive the separately bounded automatic retry.
+
 The stable `runners.check` facade orchestrates execution and re-exports its public models and selection functions. `check_models` owns report contracts, while `check_selection` owns changed-file and affected-test strategy.
 
 ## Context Builders

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

@@ -33,6 +33,8 @@ from the same declared state and ends with independently checked correctness.
 ai-dev benchmark run --suite benchmarks/agent-workflows.json --variant baseline --trials 5 --cache-state cold
 ai-dev benchmark run --suite benchmarks/agent-workflows.json --variant ai-dev --trials 5 --cache-state cold
 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
 ~~~
 
 Cold and warm results are deliberately separate and cannot be compared with each other. A
@@ -45,10 +47,21 @@ correctness, fixture identity, and a local machine profile. Token estimates use
 masked_utf8_bytes_divided_by_4; they are a stable approximation, not a model tokenizer claim.
 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
+`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
 report its real command count, validation subprocess count, and time to its first actionable
-result. The runner validates and removes that line before counting agent-visible bytes. Missing or
-invalid metrics safely fall back to the generic runner measurements.
+result. It may additionally report `iterations`, `files_read`, `selected_items`,
+`relevant_items`, `true_positive_items`, `false_negative_items`, `input_tokens`, and
+`output_tokens`. The runner derives selection precision and recall, preserves false-negative
+counts, and compares their medians. A candidate with a recall regression is rejected even when it
+is faster or smaller. The runner validates and removes the private line before counting
+agent-visible bytes. Missing or invalid metrics safely fall back to generic measurements and are
+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.
 
 ## Included suites