projscan 4.5.0 → 4.7.0

package/docs/GUIDE.md

@@ -180,14 +180,14 @@ When the agent first opens a repo, or before starting a refactor, the question i
   For short proof-command phrasing, such as `projscan start --intent "give me proof commands"`, it also routes to `projscan_regression_plan --level focused`; reviewer-proof wording with PR comments still routes to `projscan_evidence_pack`.
   For pre-push command questions, such as `projscan start --intent "what commands should I run before pushing?"`, it routes to `projscan_regression_plan --level focused` so the branch has a small verification loop before it leaves the workstation.
   For release-readiness wording, such as `projscan start --intent "what should I check before release?"`, `projscan start --intent "can I deploy this?"`, `projscan start --intent "prepare this branch for deployment"`, `projscan start --intent "what changed since last release?"`, `projscan start --intent "write a release note for this change"`, or `projscan start --intent "draft changelog entry"`, it routes to `projscan_release_train` so changelog, package, SBOM, provenance, and blockers are reviewed before deploying or publishing.
-  For product-planning questions, such as `projscan start --intent "what should we build next?"` or `projscan start --intent "plan the product roadmap"`, it routes to `projscan_workplan --mode bug_hunt` so broad product direction becomes an ordered, verifiable product-planning workplan with explicit accept, defer, or split criteria instead of a generic before-edit orientation.
+  For product-planning questions, such as `projscan start --intent "what should we build next?"` or `projscan start --intent "plan the product roadmap"`, it routes to `projscan_release_train` / `projscan release-train` so broad product direction becomes read-only roadmap planning with current post-4.4 workstreams and `evidence.roadmapPreview` instead of a generic before-edit orientation.
   For broad improvement-planning questions, such as `projscan start --intent "what should we improve next?"`, it routes to `projscan_bug_hunt` so the agent gets an actionable ranked queue; technical variants such as tests, performance, release, dependencies, or safety keep their specialized routes.
   For quick-win and low-risk improvement wording, such as `projscan start --intent "find a quick win"`, `projscan start --intent "what is a low risk improvement?"`, or `projscan start --intent "pick a small safe task"`, it routes to `projscan_bug_hunt` so a ranked, verifiable action queue is selected instead of a generic quality readout.
   For tiny-task and beginner-safe wording, such as `projscan start --intent "what can I do in five minutes?"`, `projscan start --intent "pick an easy task for me"`, or `projscan start --intent "what should an intern work on?"`, it also routes to `projscan_bug_hunt`.
   For branch-diff, PR-size, and commit-message questions, such as `projscan start --intent "what did I change since main?"`, `projscan start --intent "is this PR too large?"`, `projscan start --intent "how big is this change?"`, `projscan start --intent "write a commit message for these changes"`, or `projscan start --intent "summarize my changes for a commit"`, it routes to `projscan_pr_diff` so changed exports, imports, call sites, complexity, and fan-in are reviewed before full review.
   For branch freshness and comparison questions, such as `projscan start --intent "is my branch stale?"` or `projscan start --intent "compare my branch with main"`, it also routes to `projscan_pr_diff` so the developer checks the structural diff before rebasing or asking for review. For rebase and merge-conflict recovery, such as `projscan start --intent "rebase went wrong"` or `projscan start --intent "resolve merge conflicts"`, it routes to `projscan_preflight --mode before_merge`; post-conflict test-plan wording such as `projscan start --intent "what should I test after resolving conflicts?"` stays on `projscan_regression_plan`.
   For resume questions, such as `projscan start --intent "where did I leave off?"`, `projscan start --intent "what changed while I was away?"`, `projscan start --intent "what changed while I was offline?"`, `projscan start --intent "what changed while I was asleep?"`, `projscan start --intent "what did the last agent touch?"`, or `projscan start --intent "what did the last agent do?"`, it routes to `projscan_session { action: "touched" }` so remembered touched files are reviewed before live preflight evidence gates the next edit.
-  For parallel-agent coordination questions, such as `projscan start --intent "show coordination status for parallel agents"`, `projscan start --intent "who else is working on this?"`, `projscan start --intent "am I going to collide with another agent?"`, or `projscan start --intent "what worktrees are active?"`, it routes to `projscan_coordinate` so collisions, claims, and merge order are reviewed through one readiness verdict before editing continues. For merge-order wording, such as `projscan start --intent "what should merge first?"`, it routes to `projscan_merge_risk`; for overlap wording, such as `projscan start --intent "show me overlapping changes"`, it routes to `projscan_collision`.
+  For parallel-agent coordination questions, such as `projscan start --intent "show coordination status for parallel agents"`, `projscan start --intent "who else is working on this?"`, `projscan start --intent "am I going to collide with another agent?"`, or `projscan start --intent "what worktrees are active?"`, it routes to `projscan_coordinate` so collisions, claims, merge order, and the current-worktree-versus-remembered-session evidence boundary are reviewed through one readiness verdict before editing continues. For merge-order wording, such as `projscan start --intent "what should merge first?"`, it routes to `projscan_merge_risk`; for overlap wording, such as `projscan start --intent "show me overlapping changes"`, it routes to `projscan_collision`.
   For active-claim questions, such as `projscan start --intent "show active claims"`, it routes to `projscan_claim { action: "list" }` so owners, leases, and contention warnings are reviewed before parallel work continues.
   For file-claim requests, such as `projscan start --intent "claim src/core/start.ts for me"`, it routes to `projscan_claim`, lists active claims first, then adds the requested target only after a real agent name replaces `Needs Input`.
   For architecture-coupling questions, such as `projscan start --intent "show circular dependencies"` or `projscan start --intent "find dependency cycles"`, it routes to `projscan_coupling` with `direction: "cycles_only"` / `projscan coupling --cycles-only --format json`; broader wording such as `projscan start --intent "what modules are tightly coupled"` routes to the full fan-in, fan-out, instability, cross-package-edge, and cycle report.
@@ -204,7 +204,7 @@ When the agent first opens a repo, or before starting a refactor, the question i
 - **`projscan_preflight` / `projscan preflight`** — agent safety gate. Returns `proceed`, `caution`, or `block` with health, changed-file, review, remembered session, hotspot, plugin-policy, supply-chain, and release-scale evidence. `evidence.riskSources.currentWorktree` is current Git/worktree evidence; `evidence.riskSources.sessionMemory` is remembered handoff context. Use `--mode before_edit` at the start of work and `--mode before_commit` / `--mode before_merge` before handing off or merging; scale-only commit blocks are cautions, while merge gates still require manual release sign-off.
 - **`projscan_hotspots` / `projscan hotspots`** — files ranked by `git churn × AST cyclomatic complexity × open issues × ownership × coverage`. Pass `view: "functions"` for top-N risky individual functions across the repo (0.13+).
 - **`projscan_semantic_graph` / `projscan semantic-graph`** — stable v3 graph contract with file, function, package, and symbol nodes plus imports, exports, definitions, and calls edges. Use it when an agent needs one normalized graph shape instead of several targeted queries.
-- **`projscan_dataflow` / `projscan dataflow`** — direct, propagated, and bridge source-to-sink dataflow risks. Use it for a focused safety pass before touching command execution, raw SQL, filesystem writes, or DOM sinks.
+- **`projscan_dataflow` / `projscan dataflow`** — direct, propagated, and bridge source-to-sink dataflow risks, including framework-aware Next.js route request body and URL sources. Use it for a focused safety pass before touching command execution, raw SQL, filesystem writes, or DOM sinks.
 - **`projscan_coupling` / `projscan coupling`** — per-file fan-in / fan-out / instability plus circular-import cycles (Tarjan SCC). Use `direction: cycles_only` or `projscan coupling --cycles-only` to surface architectural debt directly.
 - **`projscan_analyze` / `projscan analyze`** — the everything report; useful at session start but verbose.
 
@@ -435,7 +435,11 @@ and a sink wrapper is surfaced even when legacy taint reachability cannot see a
 downstream call path from source to sink. By default, dataflow suppresses test-file paths,
 broad readFile/writeFile-style noise, and JavaScript RegExp.exec false positives.
 Framework request-source detection covers narrow tested patterns for Next.js, Hono,
-Express, Fastify, and Koa handlers while keeping lookalike helpers quiet.
+Express, Fastify, and Koa handlers, including Hono validator output,
+Express/Fastify/Koa request IP metadata, Fastify host/hostname and raw
+URL/header evidence, and Express/Koa header accessors plus Express
+`req.param(...)` and `req.originalUrl`, while
+keeping lookalike helpers quiet.
 
 For release hardening, `npm run check:graph-corpus` compares bundled fixture metrics against `docs/graph-corpus-baseline.json`. The gate fails only when graph coverage drops below the baseline or dataflow risks rise above it.
 
@@ -698,8 +702,8 @@ Preview the impact of upgrading a package. The default path is fully offline; pa
 - Breaking-change markers found in the CHANGELOG: scans for `BREAKING CHANGE`, `deprecated`, `removed support`, `no longer supported`, and section headers containing "breaking"
 - CHANGELOG excerpt sliced to the relevant version range (read from `node_modules/<pkg>/CHANGELOG.md`)
 - Importer list - every file in your source tree that imports the package (direct or sub-path)
-- Python manifest evidence for packages declared in `pyproject.toml`, `setup.cfg`, `setup.py`, or root `requirements*.txt`
-- Python current-version evidence from `poetry.lock` package blocks or pinned root `requirements*.txt` entries
+- Python manifest evidence for packages declared in `pyproject.toml` (including PEP 735 `dependency-groups`, Poetry dependency groups, and legacy `tool.poetry.dev-dependencies`), `setup.cfg`, `setup.py`, or root `requirements*.txt`. Root Python manifests are sufficient local evidence even before `.py` files exist.
+- Python current-version evidence from `poetry.lock` / `uv.lock` / `pdm.lock` package blocks, `conda-lock.yml` / `conda-lock.yaml` package entries, `Pipfile.lock` exact versions, pinned root `requirements*.txt`, or pinned root `constraints*.txt` entries
 
 **Example:**
 
@@ -721,7 +725,7 @@ $ projscan upgrade react --format markdown
 
 - Reads the CHANGELOG that npm already placed in `node_modules/`. If the package author doesn't ship one, you'll see "No local CHANGELOG found."
 - Without `--check-registry`, works with what's **installed** and reports `latestSource: "installed"`. With `--check-registry`, npm registry lookup is attempted and failures fall back to the installed version with `registryError`.
-- Python previews stay offline. They do not query PyPI; current-version evidence comes from supported local lockfiles or pinned root requirements.
+- Python previews stay offline. They do not query PyPI; current-version evidence comes from supported local lockfiles, pinned root requirements, or pinned root constraints.
 
 ### coverage
 
@@ -909,6 +913,10 @@ projscan doctor --format html > HEALTH.html
 ```
 
 Supported on `analyze`, `doctor`, `hotspots`, `coupling`, `pr-diff`, `review`, `impact`, and `coverage`.
+For `analyze` and `doctor`, scoped/redacted report controls also appear as a
+path-safe controls card when active.
+Path redaction keeps HTTP(S) documentation links readable while redacting
+standalone file-like path tokens from issue text.
 
 ### SARIF
 
@@ -929,9 +937,11 @@ Supported on `analyze`, `audit`, `ci`, `doctor`, and `outdated`. Each issue is e
 For shareable evidence artifacts, `analyze`, `doctor`, and `ci` accept
 `--report-policy <name>`, `--report-scope <paths>`, and `--redact-paths`. Scope
 is comma-separated and repo-relative. Redaction replaces file paths with stable
-labels while preserving correlation across issues and files in the same report.
-Direct `--report-scope` and `--redact-paths` flags override the selected preset
-for a single run.
+labels while preserving correlation across issues and files in the same report,
+including file-like path tokens in issue text that has no location anchor.
+JSON/SARIF include path-safe `reportControls` metadata, and Markdown/HTML print
+path-safe controls banners. Direct `--report-scope` and `--redact-paths` flags
+override the selected preset for a single run.
 - `properties.fixAvailable` - whether `projscan fix` can remediate it
 
 When uploaded to GitHub Code Scanning, findings appear in the **Security → Code scanning** tab and (for PRs) as inline annotations on changed lines.
@@ -1622,7 +1632,8 @@ src/
 │   ├── markdownReporter.ts      # Markdown output
 │   └── sarifReporter.ts         # SARIF 2.1.0 output
 ├── mcp/
-│   ├── server.ts                # JSON-RPC 2.0 dispatcher, stdio transport, negotiation
+│   ├── server.ts                # MCP server factory and JSON-RPC request orchestration
+│   ├── serverStdio.ts           # stdio transport loop for the CLI entry point
 │   ├── tools.ts                 # 41 MCP tools (barrel; per-tool files under tools/)
 │   ├── tokenBudget.ts           # Record-aware response truncator
 │   ├── pagination.ts            # Cursor-based pagination (opaque base64 + checksum)

package/docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # ProjScan Roadmap
 
-Last reviewed 2026-06-16.
+Last reviewed 2026-06-17.
 
 ---
 
@@ -45,7 +45,7 @@ Four plays, in order:
 3. **Become the operator, not the advisor** — stop suggesting and start acting (cross-repo, apply, security gate). ✅ Shipped in the 1.6 arc.
 4. **Expand the moat** — depth where it matters (CFG / dataflow on hot paths, more languages, sub-file embeddings, cost analytics, live PR review, plugin extensibility). Not everywhere; we're not trying to be Cody. ✅ The 1.7 → 2.0 arc turns this into a platform contract.
 5. **Coordinate the swarm** — collision detection, claims/leases, merge-risk preflight, intent routing, one-call coordination, and live coordinate watch shipped across the 3.6 through 3.7 arc, with the 4.0 tool-surface consolidation now complete. The next work is evidence: prove which commands agents reach for in real multi-worktree sessions, then deepen only the paths that prevent integration failures.
-6. **Make agent proof release-ready** — 4.1 through 4.5 turned Mission Control into a goal → mission → proof → review harness and packaged the post-4.4 implementation train: current planning surfaces, adoption examples, precise framework dataflow, scoped/redacted evidence exports, Python upgrade previews, and hotspot maintainability cleanup.
+6. **Make agent proof release-ready** — 4.1 through 4.6 turned Mission Control into a goal → mission → proof → review harness and packaged the post-4.4 implementation train: current planning surfaces, adoption examples, precise framework dataflow, scoped/redacted evidence exports, Python upgrade previews, coordination evidence, public graph types, and hotspot maintainability cleanup.
 
 We are _not_ trying to be:
 
@@ -56,9 +56,9 @@ We are _not_ trying to be:
 
 ## Now / Next / Later
 
-### Now — Post-4.5 Validation
+### Now — Post-4.6 Validation
 
-4.5.0 "Review-Ready Intelligence Train" packages the post-4.4 implementation train. The next work is validation and selective hardening from real use, not another broad feature push.
+4.6.0 "Agent Coordination And Routing Hardening" packages the latest post-4.4 implementation train. The next work is validation and selective hardening from real use, not another broad feature push or another release push.
 
 The active validation lines are:
 
@@ -70,7 +70,18 @@ The active validation lines are:
 
 Strictly **local-first** throughout: same-repo / same-machine evidence, no daemon, no cloud, no hidden network calls, no new telemetry, and no secret-value reads.
 
-Success signals: teams copy the adoption examples into real reviews, scoped/redacted artifacts are accepted by reviewers, Python upgrade previews identify useful local evidence, dataflow additions stay quiet on lookalikes, and release bug-hunts remain free of concrete defects.
+Success signals: teams copy the adoption examples into real reviews, scoped/redacted artifacts are accepted by reviewers, Python upgrade previews identify useful local evidence, coordination evidence explains multi-agent decisions, dataflow additions stay quiet on lookalikes, and release bug-hunts remain free of concrete defects.
+
+### Recently Completed — 4.6.0 (2026)
+
+**4.6.0 "Agent Coordination And Routing Hardening"** shipped the next hardening pass after the review-ready train:
+
+- Framework-gated request-source coverage now includes Next `nextUrl`, Hono URL reads, Express URL reads, Koa URL reads, and Fastify URL reads.
+- Agent hints include concrete local coordination evidence for multi-agent collision, handoff, and coordination decisions.
+- Public consumers can import code graph result types.
+- Mission Control start, intent router, review, CLI, and MCP test surfaces were split into focused suites while preserving public behavior.
+- Intent routing, code graph parsing/indexing, release evidence, upgrade preview, CLI reporting, and MCP transport helpers moved into smaller modules.
+- MCP watch IDs, request notifications, no-release continuation routing, agent harness proof routing, Python upgrade evidence, scoped dependency redaction, path-safe file links, unresolved review refs, and inspector purpose detection were tightened.
 
 ### Recently Completed — 4.5.0 (2026)
 
@@ -79,8 +90,8 @@ Success signals: teams copy the adoption examples into real reviews, scoped/reda
 - Roadmap and release-train planning now default to the current post-4.4 product lines instead of stale shipped work.
 - Adoption examples cover agent orchestration, package ownership, custom policy plugins, swarm coordination, and scoped evidence exports.
 - `analyze`, `doctor`, and `ci` can scope and redact shareable evidence with direct flags or named `reportPolicies` presets.
-- `projscan upgrade` and MCP `projscan_upgrade` support offline Python previews from manifests, Poetry lockfiles, pinned requirements, and Python importers.
-- Dataflow detects narrow Fastify and Koa request-source patterns while suppressing lookalike helpers and Koa response-body writes.
+- `projscan upgrade` and MCP `projscan_upgrade` support offline Python previews from manifests, Poetry/Pipfile/uv/PDM/Conda lockfiles, pinned requirements/constraints, and Python importers.
+- Dataflow detects narrow Fastify and Koa request-source patterns, including Fastify raw URL/header and Koa IP evidence, while suppressing lookalike helpers and Koa response-body writes.
 - Start next-action assembly and taint function identity were tightened during release readiness cleanup.
 
 ### Recently Completed — 4.4.0 (2026)

package/docs/examples/adoption-workflows.md

@@ -50,8 +50,8 @@ projscan agent-brief --intent "handoff package ownership for fastapi" --format j
 For Node packages, `upgrade` reads local `package.json`, `node_modules`, local
 CHANGELOG files, and importer evidence. For Python packages, it reads
 `pyproject.toml`, `setup.cfg`, `setup.py`, root `requirements*.txt` files,
-Poetry lockfiles, and pinned root requirements, then returns declared scope,
-current-version source, drift, and Python importers.
+Poetry/Pipfile/uv/PDM/Conda lockfiles, and pinned root requirements/constraints, then
+returns declared scope, current-version source, drift, and Python importers.
 
 Decision loop:
 

package/docs/examples/swarm-coordination.md

@@ -51,6 +51,17 @@ Read the outputs this way:
 | `coordinate` | Is the current swarm clear, cautious, or conflicted? | Use this as the one-line status in handoffs. |
 | `agent-brief` | What should the next agent know? | Include coordination hints in the next-agent packet. |
 
+The JSON reports for `collisions` and `coordinate` include an `evidence` block
+with the active command path, current worktree state, local-only source signals,
+the validation workflow above, and a reminder that session memory is separate
+from current Git/worktree evidence. The default `coordinate` console view prints
+the same session-boundary reminder inside its `Evidence` section.
+When multiple worktrees are present, `agent-brief` also carries a
+`context.coordinationHints` entry even for a clear swarm, so the next agent knows
+to validate locally with `projscan coordinate --format json`,
+`projscan coordinate --watch --interval 5 --format json`, and
+`projscan agent-brief --format json` before continuing parallel edits.
+
 For MCP clients that support long-running notifications, use the watch tool:
 
 ```text

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "4.5.0",
+  "version": "4.7.0",
   "description": "Agent-first code intelligence. MCP server (2025-03-26) with 11 AST adapters covering 12 named languages: JavaScript, TypeScript, Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, and C++; repo understanding maps (projscan_understand), stable v3 semantic graph (projscan_semantic_graph), dataflow risk engine with bridge-helper detection (projscan_dataflow), code graph, file + per-function AST cyclomatic complexity, per-function fan-in + fan-out, coupling + cycle detection, structural PR diff with HTML reporter, coverage report with HTML reporter, intent-grounded one-call PR review (projscan_review with optional `intent` arg, new taint flows, contract changes, and newDataflowRisks) and long-running PR-watch mode with structured per-bucket deltas (projscan_review_watch), first-60-seconds workflow orientation (projscan_start), agent workplans (projscan_workplan), bug-hunt queues (projscan_bug_hunt), product-line planning (projscan_release_train), evidence packs (projscan_evidence_pack), regression planning (projscan_regression_plan), agent briefs (projscan_agent_brief), quality scorecards (projscan_quality_scorecard), and preflight with supply-chain IOC evidence, rule-driven fix suggestions + mechanical apply layer with rollback (projscan_apply_fix, projscan_fix_suggest, projscan_explain_issue), source-to-sink taint analysis (projscan_taint) with truncation reporting, transitive blast-radius analysis with cross-repo mode (projscan_impact for files and symbols), cross-repo workspace registration + intelligence (projscan_workspace_graph), per-function semantic search chunks (sub-file embeddings), per-rule confidence + severity drift + cost-summary analytics with live streaming (projscan_cost_summary), stable local analyzer + reporter plugin API (projscan_plugin, CLI --reporter, opt-in via PROJSCAN_PLUGINS_PREVIEW=1), monorepo workspace awareness with cross-package import policy + per-package dependencies / outdated / audit, BM25 + optional semantic search, cursor pagination, progress notifications, context-budgeted output, and a stable-surface CI guard. CLI on the side.",
   "type": "module",
   "main": "./dist/index.js",