projscan

<div align="center">

# projscan

[![npm version](https://img.shields.io/npm/v/projscan.svg)](https://www.npmjs.com/package/projscan)
[![license](https://img.shields.io/npm/l/projscan.svg)](https://github.com/abhiyoheswaran1/projscan/blob/main/LICENSE)
[![node](https://img.shields.io/node/v/projscan.svg)](https://nodejs.org)
[![projscan health](https://img.shields.io/badge/projscan-A-brightgreen)](#quick-start)

**Agent-first code intelligence.** An MCP server that lets AI coding agents (Claude Code, Codex, Cursor, Gemini, Windsurf, Cline, Continue, Zed — any MCP-aware client) query your codebase — with a CLI for humans and a local plugin layer for team-specific policy and reporting.

[AI Agent Quick Start](#ai-agent-integration-mcp) · [CLI Quick Start](#quick-start) · [Commands](#commands) · [Full Guide](docs/GUIDE.md) · [Roadmap](docs/ROADMAP.md)

<img src="docs/projscan-mission-control.png" alt="projscan Mission Control routing a developer intent into ready actions, done criteria, and proof commands" width="760">

</div>

---

## Why?

AI coding agents are becoming the primary interface to code. When you ask an agent _"which files implement auth?"_ or _"what breaks if I bump React from 18 to 19?"_, it needs structured repo context, not raw grep output.

**projscan is code intelligence built for agents.** MCP clients get a fast, AST-backed, context-budget-aware view of your codebase: cited repo understanding, semantic graph, dataflow risks, review verdicts, hotspots, ownership, preflight gates, fix prompts, impact analysis, and durable session context. Everything is local and offline.

For teams, projscan turns that context into a repeatable PR habit. `projscan init team` creates policy, CI, ownership, and baseline memory. `projscan evidence-pack --pr-comment` gives reviewers a compact verdict with top risks, First Fix, owner routing, baseline trend memory, and exact next commands. `projscan feedback`, `projscan dogfood`, and `projscan trial` measure whether the loop actually saved time, prevented risky edits, and stayed trustworthy across real repos.

The local plugin platform lets teams add project-specific findings and render `doctor`, `analyze`, and `ci` in their own voice without changing the scan pipeline. Humans get the same information through the CLI.

**Everything is local-first. No source upload. No API keys. `.gitignore` is respected by default. `.env` values are path-only unless explicitly enabled. Anonymous product telemetry is off by default and only runs after explicit opt-in.**

```bash
npx projscan
```

<img src="docs/projscan-mission-control.gif" alt="projscan Mission Control turning a plain-language goal into shortcut commands, proof commands, and review gates" width="760">

## What's New in 4.5.0

4.5.0 packages the post-4.4 intelligence train: current roadmap planning, shareable evidence controls, Python upgrade previews, framework dataflow precision, and concrete adoption workflows.

- **Current release train.** `projscan release-train` now defaults 4.4.x and newer projects to the current 4.5.x through 4.9.x product lines instead of stale shipped 3.x/4.0 work.
- **Shareable evidence controls.** `analyze`, `doctor`, and `ci` accept `--report-policy`, `--report-scope`, and `--redact-paths`; `.projscanrc` can define reusable `reportPolicies` presets.
- **Python upgrade previews.** `projscan upgrade requests` and MCP `projscan_upgrade` now read Python manifests, Poetry lockfiles, pinned requirements, and importers offline.
- **Framework dataflow precision.** Fastify and Koa request sources are framework-gated and fixture-backed, including Koa body/query/params/header patterns without flagging response-body writes.
- **Adoption proof recipes.** New docs cover agent orchestration, package ownership, policy plugins, swarm coordination, and scoped evidence workflows teams can copy into real reviews.
- **Readiness cleanup.** The release packet documents the broad bug pass, review-risk sign-off, rollback plan, and verification evidence for the train.

<img src="docs/projscan-proof-router.png" alt="projscan intent router and proof workflow showing impact routing, setup discovery, dependency intelligence, and stable-surface guardrails" width="760">

<img src="docs/projscan-mission-proof.gif" alt="projscan saving a Mission Control bundle, reporting local mission proof, and resuming from saved proof state" width="760">

Regenerate the README media with Playwright and VHS:

```bash
npm run docs:assets
npm run docs:screenshots
npm run docs:demos
```

## Mission Execution Plan + Copyable Handoffs

`projscan start --intent "<goal>"` gives agents an execution plan with ordered phases, ready commands, blocked inputs, follow-ups, proof, and done criteria. The cursor points to the next useful step and includes MCP `tool` / `args` when projscan can call it directly.

Projscan also returns a Markdown runbook, a task card, a review gate, and a resume object. A resumed agent gets the current command, the MCP tool call, placeholder bindings, follow-up templates, the ordered checklist, and the remaining proof queue without walking the full plan. MCP and JSON clients can read `missionControl.taskCard.markdown`, the same Markdown printed by `--task-card` and written to `task-card.md`. They can also read `missionControl.reviewGate.markdown` to know when to stop, report proof, and wait for approval before starting another slice, release, publish, or deploy. `missionControl.reviewGate.worktree` adds the current worktree evidence summary and visible changed files, so review handoffs keep the state projscan computed for the start report. `missionControl.reviewGate.proof` carries the remaining proof queue with commands, MCP calls, and structured proof items for review-only handoffs. `missionControl.reviewGate.doneWhen` mirrors the mission success criteria, so review-only handoffs show the approval target beside proof and worktree evidence. `missionControl.reviewGate.policy` lists the actions blocked until explicit reviewer approval: another slice, release, publish, deploy, push, merge, and version bump. `--review-gate-json` and saved `review-gate.json` expose the full review packet without requiring callers to parse the full handoff. `--review-policy` and saved `review-policy.json` expose only the approval boundary. `missionControl.reviewGate.decisions` gives the reviewer the allowed next choices and copyable reply text: approve another slice, request changes, or review a version candidate without publishing; the same menu appears in default console output, saved bundle README files, task cards, handoff prompts, and runbook Markdown. `--review-replies` and saved `review-replies.txt` print only those reply lines when a reviewer wants the smallest approval surface. The complete handoff object carries the same gate at `missionControl.handoff.reviewGate`, so `--handoff-json` and saved `handoff.json` include the stop boundary.

Repo-local agent harnesses are surfaced in the same proof queue. When `AGENTLOOP.md` or `agentloop.config.json` exists, `projscan start` adds `npm exec agentloop -- status` as a coordination/proof command; when `.agentflight/config.json` exists, it adds `npm exec agentflight -- verify`. These commands are reported for copy/paste, saved mission bundles, and JSON clients; `projscan start` does not execute them.

Use the index when you want the menu, or call one shortcut directly:

```bash
projscan start --shortcuts --intent "<goal>"         # Show the shortcut menu
projscan start --shortcuts-json --intent "<goal>"    # Shortcut menu as JSON
projscan start --next-command --intent "<goal>"      # Current shell command
projscan start --next-tool-call --intent "<goal>"   # Current MCP call as compact JSON
projscan start --ready-tool-calls --intent "<goal>" # Current + proof MCP calls
projscan start --proof-commands --intent "<goal>"   # Remaining proof commands
projscan start --checklist --intent "<goal>"        # Ordered resume task card
projscan start --resume-json --intent "<goal>"      # Structured resume object
projscan start --handoff-json --intent "<goal>"     # Complete handoff object
projscan start --mission-script --intent "<goal>"   # Shell script: current step + proof
projscan start --save-mission .projscan/mission --intent "<goal>" # Write bundle + quickstart
projscan start --task-card --intent "<goal>"        # Paste-ready Markdown task card
projscan start --review-gate --intent "<goal>"      # Stop-and-review gate
projscan start --review-gate-json --intent "<goal>" # Review gate JSON
projscan start --review-policy --intent "<goal>"    # Review policy JSON
projscan start --review-replies --intent "<goal>"   # Copy-only reviewer replies
projscan start --runbook --intent "<goal>"          # Markdown mission runbook
projscan start --handoff-prompt --intent "<goal>"   # One-line handoff prompt
projscan start --mission .projscan/mission          # Resume from saved proof state
projscan mission-proof --mission .projscan/mission --format markdown # Paste-ready proof report
projscan mission-proof --list --format json         # List saved mission bundles
projscan mission-proof --list --needs-attention --format json # List bundles that are not passed
projscan mission-proof --latest --format markdown   # Report the newest saved mission bundle
projscan mission-proof --all --format markdown      # Roll up local saved mission bundles
projscan mission-proof --all --require-passed       # Fail if any selected bundle is not passed
projscan mission-proof --all --summary              # One-line proof status for CI logs
projscan mission-proof --mission .projscan/mission --format json     # Local proof summary for scripts
projscan mission-proof --init-baseline manual-runs.json # Create baseline template
projscan mission-proof --add-baseline-run manual-runs.json --id manual-1 --status passed --minutes-spent 25 # Record manual run
projscan mission-proof --check-baseline manual-runs.json # Validate baseline file
proj