projscan 4.4.0 → 4.5.0

package/docs/ROADMAP.md

@@ -1,6 +1,6 @@
 # ProjScan Roadmap
 
-Last reviewed 2026-06-05.
+Last reviewed 2026-06-16.
 
 ---
 
@@ -44,7 +44,8 @@ Four plays, in order:
 2. **Lean into multi-agent** — make projscan the _shared substrate_ for agent swarms. This is where the market is moving and where our context-budget design pays off. ✅ Largely shipped (1.4 Session, 1.5 Budgeted by default + Project Memory).
 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** — the Swarm Coordination arc. Plays 1–4 made projscan the best _single-agent_ code-intelligence server; the market has moved to multi-agent orchestration, where the unsolved pain is concurrent-change arbitration across parallel agents. Turn the graph + impact + session primitives into a local-first coordination layer (collision detection, claims/leases, merge-risk preflight, intent router, one-call coordinate). ✅ Shipped additively in 3.6.0. The remaining piece — consolidating the tool surface agents pay for — is breaking, so it's reserved for **4.0**.
+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.
 
 We are _not_ trying to be:
 
@@ -55,29 +56,61 @@ We are _not_ trying to be:
 
 ## Now / Next / Later
 
-### Now — Validate the Swarm Coordination arc; prepare the 4.0 surface break
+### Now — Post-4.5 Validation
 
-The **Swarm Coordination arc shipped in 3.6.0** (see Recently Completed). It was additive — five new tools, nothing removed — so it shipped as a minor release, not a major one. ("4.x" was an earlier label for the _theme_; the version is 3.6.0. The name **4.0** is reserved strictly for the one _breaking_ change below.)
+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.
 
-What's now:
+The active validation lines are:
 
-- **Validate it in real swarm usage.** The arc is built on an unvalidated bet that concurrent-change arbitration is the pain. Before deepening it, find out which of `collision` / `claim` / `merge-risk` / `coordinate` agents actually reach for, and harden from there (transitive collision recall, live `--watch` coordination, integration into `preflight` / `agent_brief`).
-- **`4.0` — tool-surface consolidation (the first breaking release since 1.0).** In progress on the `next` branch (publish held for a real deprecation window). 4.0 removes the two tools deprecated in 3.8.0 — `projscan_explain` (use `projscan_file`) and `projscan_graph` (use `projscan_semantic_graph`, which gains a targeted `query` mode that subsumes it) — taking the surface from 47 → 45. Both have drop-in replacements (see [MIGRATION-4.0.md](MIGRATION-4.0.md)). The _broader_ consolidation (routing the long tail behind `projscan_route`) is deliberately deferred until real usage signal justifies which tools to fold — same deprecate-before-remove discipline.
+- **Swarm coordination evidence.** Validate how real agents use `collisions`, `claim`, `merge-risk`, `coordinate`, and `coordinate --watch`; deepen only the coordination paths that prevent integration failures.
+- **Evidence export adoption.** Prove scoped/redacted report controls work for partner, security, and release-review handoffs without leaking unnecessary repo structure.
+- **Python upgrade coverage.** Extend lockfile support only after Poetry and pinned-requirement evidence prove useful in real repos.
+- **Framework dataflow precision.** Add more framework patterns only when each has a narrow request source, sink, and false-positive fixture.
+- **Hotspot maintainability.** Continue extracting and covering high-churn start/review/type surfaces when they show concrete review or defect risk.
 
-Strictly **local-first** throughout: same-repo / same-machine swarms via the shared store, never a daemon, cloud, or cross-machine server (that would be a SaaS non-goal).
+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: collisions prevented pre-merge, integration-failure-rate reduction, tokens saved per turn via the router, first external swarm adopter.
+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.
 
-### Recently Completed — 3.6.0 (2026)
+### Recently Completed — 4.5.0 (2026)
 
-**3.6.0 "Swarm Coordination"** turned projscan into the local-first coordination substrate for parallel agents working one repo across git worktrees:
+**4.5.0 "Review-Ready Intelligence Train"** shipped the post-4.4 implementation train:
 
-- `projscan collisions` / `projscan_collision` — same-file and dependency overlaps across in-flight worktrees, surfaced before the branches merge (reuses the import graph for blast radius).
-- `projscan claim` / `projscan_claim` — advisory claims/leases over files, dirs, or symbols, shared across worktrees, with `--ttl` expiry (so a crashed agent's claim auto-expires), contention warnings, and `prune`.
-- `projscan merge-risk` / `projscan_merge_risk` — safe integration order (merge the least-entangled branch first) plus conflict hotspots.
-- `projscan route` / `projscan_route` — map a stated goal to the right tool (additive discovery entry over the surface; deterministic, no LLM).
-- `projscan coordinate` / `projscan_coordinate` — one-call read folding it all into a `clear` / `caution` / `conflicted` readiness verdict.
-- Also: semantic search degrades to BM25 when the embedding model can't load instead of crashing. 41 → 47 MCP tools.
+- 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.
+- Start next-action assembly and taint function identity were tightened during release readiness cleanup.
+
+### Recently Completed — 4.4.0 (2026)
+
+**4.4.0 "Agent Release Harness"** turned Mission Control into a release-ready agent harness:
+
+- Repo-local AgentLoopKit and AgentFlight harness commands are surfaced as proof hints when harness files exist.
+- Product-planning intents route to verifiable bug-hunt/action planning instead of generic orientation.
+- Bug-hunt, release-train, evidence-pack, and review wording distinguish concrete fix targets from manual release sign-off actions.
+- Public type contracts are split into focused modules with a dedicated `typecheck:public-types` gate.
+- Same-SHA dirty-worktree review and directory-only verification guidance were fixed.
+- The dev dependency chain cleared the release audit gate without adding runtime dependencies.
+
+### Recently Completed — 4.0.0 through 4.3.1 (2026)
+
+- **4.0.0 "Surface Consolidation"** removed the deprecated MCP tools `projscan_explain` and `projscan_graph` after a documented deprecation cycle. CLI commands were not removed. `projscan_file` and `projscan_semantic_graph` query mode are the replacements.
+- **4.1.0 through 4.2.0 "Mission Control Handoffs"** added execution plans, cursors, runbooks, task cards, review gates, shortcut commands, and saved mission bundles.
+- **4.3.0 "Mission Outcome Loop"** added `projscan start --mission <dir>` and Mission Proof outcome summaries.
+- **4.3.1 "Mission Proof Polish"** added Markdown proof reports, saved proof output, newest/all-bundle selection, attention filters, one-line CI summaries, and reproducible demo media.
+
+### Recently Completed — 3.6.0 and 3.7.x Coordination (2026)
+
+The **Swarm Coordination arc** turned projscan into the local-first coordination substrate for parallel agents working one repo across git worktrees:
+
+- `projscan collisions` / `projscan_collision` — same-file and dependency overlaps across in-flight worktrees, surfaced before branches merge.
+- `projscan claim` / `projscan_claim` — advisory claims/leases over files, dirs, or symbols, shared across worktrees, with `--ttl` expiry, contention warnings, and `prune`.
+- `projscan merge-risk` / `projscan_merge_risk` — safe integration order plus conflict hotspots.
+- `projscan route` / `projscan_route` — deterministic goal-to-tool routing.
+- `projscan coordinate` / `projscan_coordinate` — one-call readiness verdict over collisions, claims, and merge risk.
+- `projscan coordinate --watch` / `projscan_coordinate_watch` — local polling with MCP coordination-change notifications.
 
 ### Recently Completed — 3.5.0 (2026)
 
@@ -133,11 +166,11 @@ Success signals: collisions prevented pre-merge, integration-failure-rate reduct
 
 ### Later
 
-Later work should expand the moat after 3.4.0 repo-understanding output is verified in real engineering workflows:
+Later work should deepen proven surfaces rather than add broad categories:
 
-- Broaden framework dataflow precision from narrow, tested source patterns rather than broad source-name matching.
-- Add adoption examples from real agent orchestration, package ownership, and custom policy plugin workflows.
-- Explore stronger report-export controls for teams that want path redaction or scoped evidence artifacts.
+- Add stronger sub-file and symbol-level coordination once real swarm examples show which conflicts matter.
+- Extend Python upgrade intelligence toward broader lockfile formats after Poetry and pinned-requirement evidence are proven useful.
+- Add more framework dataflow patterns only when each has a clear request source, sink, and false-positive fixture.
 
 ## Non-goals
 

package/docs/examples/adoption-workflows.md

@@ -0,0 +1,128 @@
+# Adoption Workflows
+
+These examples turn projscan from a one-off scanner into a repeatable team
+habit. They are written around the personas in `docs/PERSONAS.md`: skeptical
+senior reviewer, platform lead, product engineer, release owner, and security
+reviewer.
+
+## 1. Agent Orchestration
+
+Use this when a team is standardizing how agents start work, prove changes, and
+hand off safely.
+
+```bash
+projscan privacy-check --offline
+projscan start --intent "add billing webhook support" --format json
+projscan preflight --mode before_edit --format json
+projscan workplan --mode before_edit --format json
+projscan agent-brief --intent "handoff billing webhook work" --format json
+```
+
+Decision loop:
+
+| Persona | Reads | Decision |
+| --- | --- | --- |
+| Product engineer | `start.missionControl.readyActions` | What can I run now? |
+| Platform lead | `preflight.verdict`, coordination hints | Is parallel work safe? |
+| Senior reviewer | proof commands and done criteria | Is the handoff reviewable? |
+
+If the repo uses AgentLoopKit or AgentFlight, `projscan start` surfaces the
+local harness proof commands when their config files exist. Run those commands
+as part of the handoff proof:
+
+```bash
+npm exec agentloop -- status
+npm exec agentflight -- verify
+```
+
+## 2. Package Ownership
+
+Use this when a monorepo or platform team needs to know who owns a dependency,
+route review, or plan an upgrade.
+
+```bash
+projscan dependencies --format json
+projscan semantic-graph --query package_importers --symbol fastapi --format json
+projscan upgrade fastapi --format json
+projscan agent-brief --intent "handoff package ownership for fastapi" --format json
+```
+
+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.
+
+Decision loop:
+
+| Persona | Reads | Decision |
+| --- | --- | --- |
+| Package owner | importer list | Which app or package needs review? |
+| Release owner | drift and importer count | Is this safe for the current train? |
+| Security reviewer | audit/dependencies plus importer evidence | Is a forced update justified? |
+
+## 3. Custom Policy Plugin
+
+Use this when team-specific rules matter more than generic static analysis,
+such as service ownership, route policy, or security-sensitive directories.
+
+```bash
+projscan plugin init --kind analyzer --name team-policy
+projscan plugin validate .projscan-plugins/team-policy.projscan-plugin.json
+projscan plugin test .projscan-plugins/team-policy.projscan-plugin.json
+PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --format json
+```
+
+Start from packaged examples:
+
+- `docs/examples/plugins/policy.projscan-plugin.json`
+- `docs/examples/plugins/api-route-ownership.projscan-plugin.json`
+- `docs/examples/plugins/security-sensitive-files.projscan-plugin.json`
+- `docs/examples/plugins/team-radar.projscan-plugin.json`
+
+Decision loop:
+
+| Persona | Reads | Decision |
+| --- | --- | --- |
+| Platform lead | plugin diagnostics | Is the rule trusted enough for CI? |
+| Security reviewer | emitted issues | Does the policy catch the right risky paths? |
+| Product engineer | suggested action | Can this be fixed without tribal context? |
+
+## 4. Shareable Evidence With Path Controls
+
+Use this when a team wants to share a health or CI artifact without exposing
+repo layout or sensitive paths.
+
+```bash
+projscan analyze --report-scope src/api --redact-paths --format json > reports/api-analysis.json
+projscan doctor --report-scope src/api --redact-paths --format markdown > reports/api-health.md
+projscan ci --report-scope src/api --redact-paths --format sarif > reports/api.sarif
+```
+
+`--report-scope` keeps only issues and files under the listed repo-relative
+paths. `--redact-paths` replaces file paths with stable labels such as
+`redacted-path-1`, so reviewers can correlate evidence without seeing the
+original repo structure.
+
+When the same evidence shape is reused by a partner review, security check, or
+release train, put it in config and select it by name:
+
+```json
+{
+  "reportPolicies": {
+    "apiEvidence": {
+      "reportScope": ["src/api"],
+      "redactPaths": true
+    }
+  }
+}
+```
+
+```bash
+projscan analyze --report-policy apiEvidence --format json > reports/api-analysis.json
+projscan doctor --report-policy apiEvidence --format markdown > reports/api-health.md
+projscan ci --report-policy apiEvidence --format sarif > reports/api.sarif
+```
+
+Use direct `--report-scope` or `--redact-paths` flags with `--report-policy` for
+one-off overrides without changing the shared config preset.

package/docs/examples/swarm-coordination.md

@@ -0,0 +1,109 @@
+# Swarm Coordination Workflow
+
+Use this recipe when two or more agents, worktrees, or developers are changing
+the same repo. The goal is not to prevent parallel work; it is to make overlap,
+claim contention, and merge order visible before code lands.
+
+## Personas
+
+- Platform lead: wants low merge conflict rate and clear ownership when several
+  agents are active.
+- Product engineer: wants to keep moving without reading every sibling branch.
+- Release owner: wants a merge order and proof that high-risk overlaps were
+  reviewed before sign-off.
+
+## Start of Work
+
+Run this before the first edit in each worktree:
+
+```bash
+projscan start --intent "show coordination status for parallel agents" --format json
+projscan coordinate --format json
+projscan claim list --format json
+```
+
+If the work has a known file, claim it with a short lease:
+
+```bash
+projscan claim add src/core/start.ts --agent api-agent --ttl 2700 --format json
+```
+
+Treat a claim conflict as a routing signal. Either choose another task, split
+the file, or ask the owner to release the claim.
+
+## During Work
+
+Use the dedicated coordination tools for specific questions:
+
+```bash
+projscan collisions --format json
+projscan merge-risk --format json
+projscan coordinate --format json
+```
+
+Read the outputs this way:
+
+| Tool | Question answered | Action |
+| --- | --- | --- |
+| `collisions` | Which worktrees touch the same files or dependent files? | Move one branch first, split work, or ask for review. |
+| `claim list` | Who says they own a file, directory, or symbol right now? | Avoid edits under active leases unless agreed. |
+| `merge-risk` | Which branch should merge first? | Integrate the least-entangled branch before larger branches. |
+| `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. |
+
+For MCP clients that support long-running notifications, use the watch tool:
+
+```text
+projscan_coordinate_watch { "action": "start" }
+projscan_coordinate_watch { "action": "list" }
+projscan_coordinate_watch { "action": "stop" }
+```
+
+For CLI users, `coordinate` also supports polling:
+
+```bash
+projscan coordinate --watch --interval 5 --format json
+```
+
+The watch loop should be treated as advisory evidence. A changed notification
+or emitted watch row means rerun `projscan coordinate` before editing or merging.
+
+## Before Handoff
+
+Capture a compact handoff with coordination evidence:
+
+```bash
+projscan agent-brief --intent "handoff current parallel-agent work" --format json
+projscan preflight --mode before_commit --format json
+projscan coordinate --format json
+```
+
+Handoff text should include:
+
+- active claims you hold
+- collision count and readiness verdict
+- merge-risk order when multiple worktrees exist
+- exact proof commands already run
+- claim release command if the next agent owns the follow-up
+
+## Before Merge
+
+```bash
+projscan preflight --mode before_merge --format json
+projscan merge-risk --format json
+projscan coordinate --format json
+```
+
+Merge only when the coordination verdict is `clear` or when the release owner
+has reviewed the listed conflicts. If the verdict is `conflicted`, resolve or
+split the overlap before merging.
+
+## Evidence Gaps To Track
+
+These are the next hardening targets for real swarm usage:
+
+- transitive collision recall: prove dependent-file conflicts are caught, not
+  only same-file conflicts
+- live watch adoption: prove agents notice and act on coordination changes
+- preflight and agent-brief integration: prove the same coordination facts show
+  up where agents already look before editing or handing off

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "4.4.0",
+  "version": "4.5.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",
@@ -21,6 +21,8 @@
     "docs/demos/projscan-mission-control.tape",
     "docs/demos/projscan-mission-proof.tape",
     "docs/plugin.schema.json",
+    "docs/examples/adoption-workflows.md",
+    "docs/examples/swarm-coordination.md",
     "docs/projscan-mission-control.png",
     "docs/projscan-mission-control.gif",
     "docs/projscan-proof-router.png",