projscan 4.4.0 → 4.6.0

package/dist/utils/configSources.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configSources.js","sourceRoot":"","sources":["../../src/utils/configSources.ts"],"names":[],"mappings":"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"}

package/dist/utils/configTaint.d.ts

@@ -0,0 +1,2 @@
+import type { ProjscanConfig } from '../types/config.js';
+export declare function applyTaint(obj: Record<string, unknown>, out: ProjscanConfig): void;

package/dist/utils/configTaint.js

@@ -0,0 +1,15 @@
+export function applyTaint(obj, out) {
+    if (!obj.taint || typeof obj.taint !== 'object')
+        return;
+    const t = obj.taint;
+    const taint = {};
+    if (Array.isArray(t.sources)) {
+        taint.sources = t.sources.filter((v) => typeof v === 'string' && v.length > 0);
+    }
+    if (Array.isArray(t.sinks)) {
+        taint.sinks = t.sinks.filter((v) => typeof v === 'string' && v.length > 0);
+    }
+    if (Object.keys(taint).length)
+        out.taint = taint;
+}
+//# sourceMappingURL=configTaint.js.map

package/dist/utils/configTaint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"configTaint.js","sourceRoot":"","sources":["../../src/utils/configTaint.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,UAAU,CAAC,GAA4B,EAAE,GAAmB;IAC1E,IAAI,CAAC,GAAG,CAAC,KAAK,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;QAAE,OAAO;IACxD,MAAM,CAAC,GAAG,GAAG,CAAC,KAAgC,CAAC;IAC/C,MAAM,KAAK,GAAyC,EAAE,CAAC;IACvD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;QAC7B,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC9F,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3B,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1F,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,MAAM;QAAE,GAAG,CAAC,KAAK,GAAG,KAAK,CAAC;AACnD,CAAC"}

package/docs/GUIDE.md

@@ -187,7 +187,7 @@ When the agent first opens a repo, or before starting a refactor, the question i
   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.
 
@@ -434,6 +434,12 @@ graph. Bridge risks are graph-backed dataflow additions: a wrapper that calls a
 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, 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.
 
@@ -688,7 +694,7 @@ Each finding becomes a SARIF result with `ruleId: audit-<pkg>`, severity mapped
 projscan upgrade <package>
 ```
 
-Preview the impact of upgrading a package. The default path is fully offline; pass `--check-registry` when you explicitly want npm registry lookup for the current latest version.
+Preview the impact of upgrading a package. The default path is fully offline; pass `--check-registry` when you explicitly want npm registry lookup for the current latest npm version.
 
 **What you get:**
 
@@ -696,6 +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` (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:**
 
@@ -717,6 +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, pinned root requirements, or pinned root constraints.
 
 ### coverage
 
@@ -882,6 +891,8 @@ Machine-readable output. Useful for piping into other tools, storing results, or
 ```bash
 projscan analyze --format json | jq '.issues[] | select(.severity == "error")'
 projscan analyze --format json > analysis.json
+projscan analyze --report-scope src/api --redact-paths --format json > scoped-analysis.json
+projscan analyze --report-policy apiEvidence --format json > scoped-analysis.json
 ```
 
 ### Markdown
@@ -902,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
 
@@ -918,6 +933,15 @@ Supported on `analyze`, `audit`, `ci`, `doctor`, and `outdated`. Each issue is e
 - `message.text` - the issue description
 - `locations` - real file + line/column when the analyzer can supply them (security findings include line numbers); project-level issues anchor to repo root
 - `properties.category` - the analyzer category (`security`, `formatting`, `architecture`, …)
+
+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,
+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.
@@ -951,6 +975,12 @@ ProjScan loads a project-wide config from one of:
   "severityOverrides": {
     "missing-prettier": "info"
   },
+  "reportPolicies": {
+    "apiEvidence": {
+      "reportScope": ["src/api", "packages/backend"],
+      "redactPaths": true
+    }
+  },
   "hotspots": {
     "limit": 20,
     "since": "6 months ago"
@@ -970,6 +1000,7 @@ ProjScan loads a project-wide config from one of:
 | `scan.offline`        | boolean                                          | Block projscan network-capable features: telemetry sending, `audit`, registry checks, and optional semantic model loading. Default `false`.                   |
 | `disableRules`        | string[]                                         | Silence rules by id. Exact match (`missing-prettier`) or wildcard prefix (`large-*`).                                                                         |
 | `severityOverrides`   | `Record<string, 'info' \| 'warning' \| 'error'>` | Remap a rule's severity. Useful for downgrading project-specific false positives without disabling them.                                                      |
+| `reportPolicies`      | `Record<string, { reportScope?: string[]; redactPaths?: boolean }>` | Named evidence export presets selected with `--report-policy <name>` on `analyze`, `doctor`, and `ci`.                                      |
 | `hotspots.limit`      | number (1–100)                                   | Default limit for `projscan hotspots`.                                                                                                                        |
 | `hotspots.since`      | string                                           | Default git history window for `projscan hotspots`.                                                                                                           |
 
@@ -1059,6 +1090,9 @@ Example GitHub Actions snippet:
 | `--offline`         | Block projscan network-capable features for this run                                        |
 | `--changed-only`    | Scope to files changed vs base ref (applies to `analyze`, `doctor`, `ci`)                   |
 | `--base-ref <ref>`  | Git base ref for `--changed-only` (default: origin/main)                                    |
+| `--report-policy <name>` | Use a named report policy preset from config (`analyze`, `doctor`, `ci`)              |
+| `--report-scope <paths>` | Comma-separated repo-relative paths to include in exported evidence (`analyze`, `doctor`, `ci`) |
+| `--redact-paths`    | Replace file paths in exported evidence with stable labels (`analyze`, `doctor`, `ci`)      |
 | `--verbose`         | Show debug-level logging - useful for diagnosing scan issues                                |
 | `--quiet`           | Suppress all non-essential output (spinners, status messages)                               |
 | `-V, --version`     | Print the version number                                                                    |
@@ -1598,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-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/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)
+
+**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/Pipfile/uv/PDM/Conda lockfiles, and pinned root requirements/constraints, 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,120 @@
+# 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. |
+
+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
+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.6.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",