Projscan

projscan

Local proof for AI-assisted engineering. projscan gives agents and engineers the repo context, risk checks, proof commands, and review gates they need before editing, handing off, or preparing a release candidate.

Install · Daily workflows · MCP Setup · Commands · Trust · Full Guide

---

Use It For

Use projscan when an agent asks one of these questions:

• Which files should I read before changing this feature?
• Which proof commands should I run before handoff?
• Which risks need fixes, reviewer attention, or release sign-off?
• Which risk should I fix first?
• Did the agent stay inside the approved change boundary?

projscan runs core scans on your machine. It respects .gitignore, keeps .env values out of scans unless you opt in, and exposes the same evidence through a CLI and a 51-tool MCP server. The language layer uses 11 AST adapters covering 12 named languages.

Your agent / engineer

(Codex, Claude Code, Cursor, CI, your scripts) | intent, diff, repo files, feedback, proof requests v +----------------------------------------------------------------+

| | | +- allowed files | | | +- forbidden files | | | +- proof receipt | | | +- change passport | | | +- review gate | | | +- live guard | | +- bounded extraction | | | +- regression test first | | | +- leave unchanged | | +- evidence strength | | +- trust memory | | +- AgentLoopKit handoff | | | | CLI + MCP tools, no account, telemetry off by default | +----------------------------------------------------------------+ | next safe action, exact proof commands, handoff packet v Reviewer / CI / LLM provider (only the evidence you choose to pass along)

Install

npm install -g projscan

projscan start

Run without a global install:

npx projscan start

Check the trust boundary first:

projscan privacy-check

projscan start --intent "what can projscan read?" projscan start --intent "does projscan read .env values?"

Daily workflows

Use these four workflows before scanning the full command catalog.

Before editing a feature

projscan start --intent "what files do I need to change for auth?"

projscan start --intent "what should we build next?" # Routes to a before-edit implementation workplan projscan start --intent "is my agent allowed to change billing retry logic?" projscan understand --view change --intent "add auth token refresh" --format json projscan prove --intent "is my agent allowed to change billing retry logic?" projscan preflight --mode before_edit --format json

You get a cited change map, read-first files, likely touched files, blocked inputs, an executable Proof Contract, and a before-edit proof gate. Agent-permission intents route to projscan prove, so start can hand the next agent a contract path instead of a broad checklist.

Success criteria: the agent can name the files to read first, the likely files to touch, the forbidden files to avoid, and the proof commands to run before editing.

Verified change workflow

projscan start --intent "is my agent allowed to change billing retry logic?"

projscan prove --intent "is my agent allowed to change billing retry logic?" --save-contract .projscan/proof-contract.json

Make the bounded edit, then run the proof command.

projscan prove --run -- npm test -- tests/billing/retry.test.ts projscan prove --changed --contract .projscan/proof-contract.json --format markdown projscan passport --contract .projscan/proof-contract.json --format markdown projscan proof-broker --contract .projscan/proof-contract.json --pr-comment projscan review-gate --contract .projscan/proof-contract.json --pr-comment

The command path is start -> prove -> run -> changed. Make the bounded edit after the contract exists and before prove --run. start chooses the contract workflow. prove --intent writes .projscan/proof-contract.json only when --save-contract is present. prove --run -- executes a local proof command, records the exit code, captures a redacted log, and fingerprints the current changed files. prove --record-command remains available for imported CI or external evidence when projscan did not run the command. prove --changed checks the current working tree against the contract and local ledger.

You get a Proof Contract before edits and a Proof Receipt after edits. The contract names allowed files, forbidden files, risky contracts, likely tests, missing regression-test evidence, proof commands, safe change shape, rollback, confidence, reviewer guidance, and proofRequirements for each risk surface. The receipt checks the real working tree against that contract and classifies changed files as allowed production, expected tests, documentation, generated proof artifacts, config/security drift, forbidden touches, or unexpected production. The receipt reports proof replay status, Proof Sufficiency, risk delta, commit readiness, and a reviewer checklist.

Sibling Baseframe harness directories (.agentloop/, .agentflight/) are classified as harness evidence, not scope drift: AgentLoopKit and AgentFlight write session state, task status transitions, and verification reports there as part of their sanctioned workflows, so those writes stay informational in the receipt and never trip forbiddenTouched, block commit readiness, or stop the review gate. Auto-generated contracts no longer list them in forbiddenFiles, receipts ignore those entries in contracts saved by older versions, and Team Proof Recipe forbiddenFiles entries are read the same way. To forbid production paths, keep using forbiddenFiles or Team Proof Recipes for non-harness locations.

Dependency-change intents keep their own scope executable: when prove --intent describes a dependency or tooling version change (for example "upgrade projscan to 5.0.1"), the generated contract places package.json and package-lock.json in allowedFiles instead of forbiddenFiles. Unrelated intents keep the manifests forbidden by default. Contract artifacts are restricted to .projscan/proof-contract.json or .projscan/proof-contracts/ .json inside the project root; --save-contract and --contract reject other paths.

Proof Replay records command, exit code, duration, changed-file fingerprint, redacted summary, log path, and source in .projscan/proof-ledger.jsonl. Executed proof logs stay under .projscan/proof-logs/. Ledger matching normalizes package-runner prefixes, so npx projscan assess --mode fix-first --format json, pnpm exec projscan ..., and node_modules/.bin/projscan ... all satisfy a required projscan assess --mode fix-first --format json. prove --changed marks proof as passed, missing, failed, partial, or stale. The receipt JSON includes proofReplay with a replay timeline, changedAfterProof, replay command, and local receipt fingerprint. If the agent edits new files after proof ran, the receipt says the proof is stale before a reviewer reads the diff.

Proof Sufficiency estimates whether the local ledger covers each changed surface. proofSufficiency marks rows as strong, adequate, weak, missing, stale, or failed, then lists the exact gaps reviewers need to resolve.

Team Proof Recipes let a repo encode required proof for sensitive paths in proofRecipes; when a matching recipe is configured, prove --intent adds that recipe's commands, reviewers, and forbidden files to the Proof Contract. prove --changed and projscan evidence-pack --pr-comment then show missing recipe proof, required reviewers, and recipe drift in the Proof Receipt. The recipe does not run proof commands by itself; use prove --run -- or prove --record-command to add evidence to the local ledger. Saved contracts are the source of truth for prove --changed; update the contract when a team recipe changes.

Every prove report includes verifiedWorkflow, a compact JSON summary for agents and MCP clients. It names the phase, next action, next command, scope status, proof status, proof sufficiency status, risk delta direction, reviewer decision, and stale/missing/failed proof flags.

projscan passport turns the contract and receipt into one handoff artifact. It names allowed files, forbidden files, changed files, proof replay status, Proof Sufficiency, reviewer action, and next commands. Save it when a reviewer or another agent needs the whole change story in one JSON file:

projscan passport \

--intent "is my agent allowed to change billing retry logic?" \ --save-contract .projscan/proof-contract.json \ --output .projscan/passport.json

Use projscan proof-broker to build a PR Passport from the same passport evidence. It names required proof rows, missing or stale proof commands, required reviewers from Team Proof Recipes, risky changed files, and the next commands a reviewer should ask for:

projscan proof-broker --intent "<change>" --bootstrap-contract

projscan proof-broker --contract .projscan/proof-contract.json --pr-comment

--bootstrap-contract writes a new Proof Contract only when explicitly requested. It does not execute proof commands and does not silently widen scope.

Use projscan review-gate to produce a review decision from the PR Passport. It reports ready, needs-proof, drifted, or blocked, says whether review can proceed, itemizes proof debt, names the recontract command when scope moved, and can fail CI until the proof debt is gone:

projscan review-gate --intent "<change>" --bootstrap-contract

projscan review-gate --contract .projscan/proof-contract.json --pr-comment projscan review-gate --contract .projscan/proof-contract.json --ci --fail-on-needs-proof

projscan guard checks the current working tree against a saved Proof Contract. Use it after an agent edits files, or run --watch during a session:

projscan guard --contract .projscan/proof-contract.json

projscan guard --contract .projscan/proof-contract.json --watch

<img src="docs/projscan-live-guard.png" alt="projscan Live Guard watch outpu