ProjScan

Features

What it does well.

See it in action

A closer look.

~ npx projscan start

~ projscan mcp

~ projscan hotspots

~ projscan search

What's new

5.0.2: Dependency-intent contracts keep their manifests in scope.

Ask `prove --intent` for a dependency or tooling version change, say "upgrade projscan to 5.0.1", and 5.0.2 puts `package.json` and `package-lock.json` in `allowedFiles` instead of `forbiddenFiles`. The upgrade contract no longer blocks its own intent. Unrelated intents keep the manifests forbidden by default, so a billing-retry contract still catches a stray dependency bump. 5.0.2 also hardens the Baseframe suite interop from 5.0.1, so ProjScan reads sanctioned harness writes as harness evidence rather than scope drift. The 5.0.0 review loops are unchanged: 51 MCP tools, 11 AST adapters covering 12 named languages, explicit bootstrap on `proof-broker` and `review-gate`, review stays local, and MCP returns evidence without executing proof.

Upgrade contracts allow their manifests

When the intent describes a dependency or tooling version change, ProjScan now writes `package.json` and `package-lock.json` into `allowedFiles` instead of `forbiddenFiles`, so an upgrade contract no longer blocks its own intent. Unrelated intents keep the manifests forbidden by default.

Normalized harness paths

ProjScan strips leading `./` prefixes and normalizes separators before it classifies harness evidence, so it recognizes externally supplied changed-file paths (MCP, imported proof) as sanctioned `.agentloop/` and `.agentflight/` writes. It also de-duplicates changed files at intake, so one harness write never counts twice in scope drift.

The recipe harness guard

Team Proof Recipe `forbiddenFiles` entries now carry the same harness-path guard as Proof Contract `forbiddenFiles`. A recipe that forbids `.agentloop/**` or `.agentflight/**` no longer flags sanctioned harness evidence as forbidden scope drift.

Sibling harness writes

Proof Receipts still classify sibling Baseframe harness writes (`.agentloop/`, `.agentflight/`) as informational harness evidence, and Proof Ledger matching still normalizes package-runner prefixes: `npx`, `npm exec`, `pnpm exec` and `dlx`, `yarn exec` and `dlx`, `bunx`, and `node_modules/.bin`.

Explicit bootstrap, unchanged

`projscan proof-broker --intent "<text>" --bootstrap-contract` and `projscan review-gate --intent "<text>" --bootstrap-contract` write the next scoped Proof Contract only when you ask for it, then return bootstrap-aware PR Passport output and reviewer guidance. Leave the flag off and ProjScan mints nothing.

Review Gate evidence, unchanged

`review-gate --contract .projscan/proof-contract.json --pr-comment` prints Review Gate Markdown carrying status, the allow-review decision, reviewer action, proof debt, recontract guidance, bootstrap status when present, required reviewers, next commands, and artifact paths; `--ci --fail-on-needs-proof` prints a compact CI summary and exits non-zero until the gate is `ready`. The JSON includes `kind: "review-gate"`, `decision`, `proofDebt`, `recontract`, `bootstrap`, `requiredReviewers`, `nextCommands`, `prComment`, artifacts, and the embedded Proof Broker report. Artifacts land in `.projscan/review-gate.json` or `.projscan/review-gates/<name>.json`, and ProjScan rejects traversal, symlink targets, non-JSON files, and existing files that are not Review Gate artifacts.

MCP and exports

MCP exposes `projscan_review_gate`, keeping the tool count at 51; it returns gate evidence and does not run local proof commands. MCP still exposes `projscan_prove` and can create, replay, and record imported proof, while CLI `prove --run` executes local commands. The package exports `computeReviewGate()` plus Review Gate report, decision, proof-debt, recontract, artifact, and PR-comment types, and every existing proof workflow (Proof Broker, passport, Live Guard, Proof Ledger, Proof Replay, Proof Sufficiency, Team Proof Recipes, stale, failed, and changed-after-proof handling, and evidence-pack receipt sections) stays independent.

Proof workflows

The proof replay trust loop.

Under the suite export, the proof loop runs end to end: save a Proof Contract, run or record the required proof, replay the final diff, and hand reviewers a receipt that shows scope, proof freshness, sufficiency gaps, required reviewers, and changed-after-proof files. Core scans run locally, source is not uploaded, and telemetry stays off until you opt in.

Richer Proof Replay

`projscan prove --changed` reports replay status, timeline events, changed-after-proof files, the replay command, and a receipt fingerprint, so a reviewer can see what the proof covered and what shifted after it ran.

Proof Sufficiency

The receipt tells reviewers whether proof is strong, adequate, weak, missing, stale, or failed across the changed risk surfaces, so weak or missing proof is visible instead of assumed.

Team Proof Recipes

`.projscanrc.json` `proofRecipes` let teams require path-matched proof commands, reviewers, and forbidden files for sensitive areas, so a change under `src/billing/**` carries its own proof bar.

PR comments carry the receipt

`projscan evidence-pack --pr-comment` includes Proof Receipt evidence when available: proof replay, proof sufficiency, recipe gaps, required reviewers, changed-after-proof files, and receipt fingerprints.

Hardened proof reads

Proof Contract and Proof Ledger reads reject symlink escapes, proof logs redact more standalone token and private-key shapes, and saved Mission Control scripts reject shell control syntax before running proof commands.

MCP creates, replays, records

MCP exposes `projscan_prove` and `projscan_passport`, with the server now at 51 tools after Review Gate and the Proof Broker. Over MCP an agent can create a Proof Contract, replay the diff, record imported proof, and read passport, broker, and review-gate evidence. Only the CLI `prove --run` executes local commands.

The loop

Goal, mission, proof, review.

One workflow runs from a plain-language goal to gated evidence. Each step is a command you hand to the next agent.

Route a goal

`projscan start --intent "<goal>"` infers the workflow and returns an execution plan with a current cursor, route confidence, ready actions, done criteria, proof commands, and a review gate. State the goal; ProjScan picks the tools.

Save the mission

`--save-mission <dir>` writes a bundle: README, prompts, runbook, task card, review gate, JSON handoff files, proof logs, and executable `mission.sh`, `status.sh`, and `review.sh`. A fresh or sleeping agent resumes from the bundle without rereading the report.

Run and resume proof

`mission.sh` runs the next steps, `status.sh` reports where the work stands, and `review.sh` gates approval. Proof status lands in `proof-logs/summary.json`, and `projscan start --mission <dir>` resumes from that saved pass or fail state.

Review the evidence

`projscan mission-proof` summarizes local proof across one or many bundles: Markdown for humans, JSON for agents. `--latest`, `--all`, `--needs-attention`, `--summary`, `--require-passed`, and `--write` turn saved bundles into release-review artifacts, none of which upload source.

How it works in practice

Practical workflows.

From first clone to a gated production merge.

PR evidence comment

`projscan evidence-pack --pr-comment` posts a Reviewer Decision (ship, review, or fix-first) with top risks, CODEOWNERS routing for who owns each file, the next commands, and what changed since your local baseline.

Team bootstrap

`projscan init team` writes a starter policy, a GitHub Action, CODEOWNERS hints, and first-run setup, wiring a new repo in one command.

MCP setup that works

`projscan mcp doctor --client claude|cursor|codex` checks your config and prints a paste-ready snippet; `npx projscan init mcp --client all` wires it in one shot. Registry id: io.github.abhiyoheswaran1/projscan.

Trust calibration

Blocks are rare and mean real semantic risk: new bridge-helper dataflow paths, audit findings above threshold, or failing preflight gates. Scale-only concerns return caution with a manual-review note. A local baseline means later runs report deltas, not every old finding.

Stable surface

What 5.x means.

A versioned contract your agents and CI can depend on.

Semver covers

MCP tool names and schemas, CLI commands and documented flags, exit codes, the CLI JSON envelope (schemaVersion 2), the analyzer and reporter plugin contract (schemaVersion 1), and the public API exports.

Consolidated in 4.0

4.0 removed projscan_explain and projscan_graph after a full deprecation release; projscan_file and projscan_semantic_graph (query mode) replace them. Everything since has been additive, and the 5.0 line continues the same proof-first surface: explicit bootstrap loops on Review Gate and the Proof Broker in 5.0.0, sharper contract scoping and harness-path handling in 5.0.1 and 5.0.2, no tool removals, and every other 2.x, 3.x, and 4.x surface stays.Migration guide: docs/MIGRATION-4.0.md

Languages and runtime

Eleven AST adapters cover twelve named languages: JavaScript and TypeScript share one Babel adapter; Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, and C++ each use a Tree-sitter adapter. Node.js 18+ (20+ for recursive Linux watch), on macOS, Linux, and Windows. Every release ships npm provenance and a CycloneDX SBOM, checked against the installed tarball by the repo maintainer with `npm run release:check`.

Privacy

Offline by default: no source upload, no API key, telemetry off until you opt in. `projscan privacy-check` prints what ProjScan can read, write, or contact, and `--offline` blocks every network surface. Your repo never leaves the machine.