docs: stage 0.8.7 release notes

CHANGELOG.md

@@ -18,11 +18,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `agentshield ci install` to generate a GitHub Actions workflow.
 - `agentshield ci install --baseline <path>` to generate GitHub Actions
   workflows that filter known findings through a baseline file.
+- `[scan] include` and `[scan] exclude` path filters for scoping scans from
+  `.agentshield.toml`.
+- MCP subdirectory scans that keep source parsing bounded to the requested
+  directory while reading project metadata from an ancestor root when needed.
+- Explain-mode scan-root, metadata-root, and blocking-finding hotspot summaries.
 
 ### Changed
 
 - Console scan output now separates runtime-risk findings from supply-chain
   hygiene recommendations before listing individual findings.
+- `scan --explain` now highlights concentrated runtime, supply-chain, and rule
+  hotspots so first-run triage points at the highest-value directories/files.
 
 ### Fixed
 
@@ -38,6 +45,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `aiconnai/agentshield@main` action ref.
 - The GitHub Action now resolves release assets from the canonical
   `aiconnai/agentshield` repository.
+- Path filters now also apply to dependency and provenance metadata files, so
+  excluded manifests do not produce metadata-derived findings.
 
 ## [0.8.6] - 2026-06-07
 

README.md

@@ -19,7 +19,8 @@ call those tools.
 
 It runs as a CLI, GitHub Action, or library, keeps source code on your machine,
 and emits console, JSON, SARIF for GitHub Code Scanning, and standalone HTML
-reports. The current release line is `0.8.6`.
+reports. The current release line is `0.8.6`; 0.8.7 release notes are staged
+for the path-filter and first-run explain UX work.
 
 ## At a glance
 
@@ -238,6 +239,8 @@ AgentShield runs all matching adapters in a repository instead of stopping at th
 | `agentshield guard --mcp-proxy [-- <server cmd...>]` | EXPERIMENTAL: evaluate line-delimited MCP JSON-RPC `tools/call` messages, block unsafe calls, and either emit forward markers or bridge stdio to a spawned downstream MCP server when built with the `runtime-guard` feature. |
 
 Useful `scan` options include `--config`, `--format`, `--fail-on`, `--output`, `--ignore-tests`, `--explain`, `--baseline`, `--write-baseline`, and `--emit-egress-policy`.
+Configured `[scan] include` and `[scan] exclude` filters scope source and
+metadata-derived findings before detectors run.
 
 For mature repositories with existing findings, write a baseline first and use
 it in CI:
@@ -249,7 +252,8 @@ agentshield ci install --baseline .agentshield-baseline.json
 ```
 
 `--explain` is intentionally console-only. It will not append text to JSON,
-SARIF, or HTML output.
+SARIF, or HTML output. Explain output includes the scan root, metadata root
+when different, and hotspot summaries for concentrated blocking findings.
 
 ---
 
@@ -399,4 +403,5 @@ cargo run -- scan tests/fixtures/mcp_servers/vuln_cmd_inject
 cargo run -- list-rules
 ```
 
-For release-specific notes, see `docs/releases/0.8.6.md` and `docs/RELEASE_CHECKLIST.md`.
+For release-specific notes, see `docs/releases/0.8.6.md`,
+`docs/releases/0.8.7.md`, and `docs/RELEASE_CHECKLIST.md`.

docs/NEXT_STEPS.md

@@ -1,6 +1,6 @@
 # Next Steps — Post v0.1.0
 
-Status: v0.8.6 release prep. 7 framework/client adapters (MCP, OpenClaw, Hermes Agent, CrewAI, LangChain, GPT Actions, Cursor Rules), 18 detectors (SHIELD-001..018), VS Code extension. Fingerprints, suppressions, baseline diffing, taint path analysis, egress policy generation, DSSE attestation (`certify`), operator override layering, experimental `guard --stdin`, and experimental bidirectional `guard --mcp-proxy` transport. TypeScript tree-sitter parser, crates.io, Homebrew, GitHub Action e2e, real-world validation, cross-file validation tracking, PR inline annotations - all done.
+Status: v0.8.7 release prep. 7 framework/client adapters (MCP, OpenClaw, Hermes Agent, CrewAI, LangChain, GPT Actions, Cursor Rules), 18 detectors (SHIELD-001..018), VS Code extension. Fingerprints, suppressions, baseline diffing, taint path analysis, egress policy generation, DSSE attestation (`certify`), operator override layering, scan include/exclude filters, MCP subdirectory scans, explain hotspot summaries, experimental `guard --stdin`, and experimental bidirectional `guard --mcp-proxy` transport. TypeScript tree-sitter parser, crates.io, Homebrew, GitHub Action e2e, real-world validation, cross-file validation tracking, PR inline annotations - all done.
 
 ---
 
@@ -16,6 +16,24 @@ Runtime guard work is planned as an experimental extension to AgentShield's curr
 
 ---
 
+## v0.8.7 release prep
+
+The current release-prep scope covers first-run scanner scoping and triage:
+
+- `[scan] include` and `[scan] exclude` path filters for source and
+  metadata-derived findings.
+- MCP subdirectory scans that preserve the requested source boundary while
+  reading ancestor project metadata.
+- `scan --explain` root reporting and blocking-finding hotspot summaries.
+
+Remaining follow-up before tagging:
+
+- AGENT-31 GitHub Action/e2e coverage for path filters plus MCP subdirectory
+  scans is included in the release-prep batch.
+- Final release checklist pass and version/tag bump when publication is ready.
+
+---
+
 ## ~~1. Real-World Validation~~ — Done
 
 Completed Feb 20, 2026. Scanned 7 Anthropic reference MCP servers. See `docs/VALIDATION_REPORT.md` for full results.

docs/releases/0.8.7.md

@@ -0,0 +1,40 @@
+# AgentShield 0.8.7 Release Notes
+
+Release date: pending
+
+## Scope
+
+This release prepares the static scanner UX improvements from AGENT-25,
+AGENT-27, and AGENT-28. It keeps the scanner output contracts stable while
+making first-run scans easier to scope and triage.
+
+## Notable changes
+
+- Added `[scan] include` and `[scan] exclude` path filters in
+  `.agentshield.toml`. Include patterns select eligible files, and exclude
+  patterns win when both match.
+- Path filters apply before source parsing and to metadata-derived dependency
+  and provenance findings. Excluding `package.json`, `requirements.txt`, or
+  similar manifests suppresses findings derived from those files.
+- MCP scans can start from a subdirectory such as `src/mcp` while still reading
+  MCP project metadata from an ancestor root. Source files outside the requested
+  scan root are not parsed.
+- `scan --explain` now reports the requested scan root and, when different, the
+  metadata root used for project metadata.
+- `scan --explain` now summarizes blocking-finding hotspots by runtime-risk
+  concentration, supply-chain concentration, and rule concentration.
+
+## Compatibility
+
+- Console, JSON, SARIF, HTML, and DSSE output contracts remain stable.
+- `--explain` stays console-only and does not alter machine-readable JSON,
+  SARIF, or HTML artifacts.
+- Existing scans with no `[scan] include` or `[scan] exclude` configuration keep
+  the same broad file eligibility behavior.
+
+## Readiness
+
+- Covered by Rust integration tests for path filters, MCP subdirectory scans,
+  and explain hotspot rendering.
+- GitHub Action/e2e coverage for path filters plus MCP subdirectory scans is
+  covered by the AGENT-31 workflow fixture.