projscan 4.9.2 → 4.9.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (11) hide show
  1. package/README.md +208 -1354
  2. package/dist/projscan-sbom.cdx.json +6 -6
  3. package/dist/tool-manifest.json +2 -2
  4. package/docs/demos/projscan-4-1-demo.html +8 -8
  5. package/docs/demos/projscan-mission-control.tape +2 -2
  6. package/docs/demos/projscan-mission-proof.tape +9 -5
  7. package/docs/projscan-mission-control.gif +0 -0
  8. package/docs/projscan-mission-control.png +0 -0
  9. package/docs/projscan-mission-proof.gif +0 -0
  10. package/docs/projscan-proof-router.png +0 -0
  11. package/package.json +1 -1
package/README.md CHANGED
@@ -5,277 +5,47 @@
5
5
  [![npm version](https://img.shields.io/npm/v/projscan.svg)](https://www.npmjs.com/package/projscan)
6
6
  [![license](https://img.shields.io/npm/l/projscan.svg)](https://github.com/abhiyoheswaran1/projscan/blob/main/LICENSE)
7
7
  [![node](https://img.shields.io/node/v/projscan.svg)](https://nodejs.org)
8
- [![projscan health](https://img.shields.io/badge/projscan-A-brightgreen)](#quick-start)
8
+ [![projscan health](https://img.shields.io/badge/projscan-A-brightgreen)](#install)
9
9
 
10
- **Local proof for AI-assisted engineering workflows.** An MCP server and CLI that helps agents and humans answer three review questions: what to read before editing, what to fix before handoff, and what needs review before a release candidate.
10
+ **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.
11
11
 
12
- [AI Agent Quick Start](#ai-agent-integration-mcp) · [CLI Quick Start](#quick-start) · [Commands](#commands) · [Full Guide](docs/GUIDE.md) · [Roadmap](docs/ROADMAP.md)
12
+ [Install](#install) · [Daily workflows](#daily-workflows) · [MCP Setup](#mcp-setup) · [Commands](#command-map) · [Trust](#trust-model) · [Full Guide](docs/GUIDE.md)
13
13
 
14
- <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">
14
+ <img src="docs/projscan-mission-control.png" alt="projscan Mission Control routing a saved mission into proof status, remaining work, outcome commands, and review gates" width="760">
15
15
 
16
16
  </div>
17
17
 
18
18
  ---
19
19
 
20
- ## Why?
20
+ ## Use It For
21
21
 
22
- AI coding agents are becoming a common 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 and proof commands, not a broad scan to summarize.
22
+ Use projscan when an agent asks one of these questions:
23
23
 
24
- **projscan is a local evidence tool for agent-assisted engineering.** It is most useful in three daily workflows: before editing, before handoff or commit, and before release-candidate review. Start there before scanning the full command catalog.
24
+ - Which files should I read before changing this feature?
25
+ - Which proof commands should I run before handoff?
26
+ - Which risks need fixes, reviewer attention, or release sign-off?
25
27
 
26
- MCP clients and humans can still query repo maps, semantic graph evidence, dataflow risks, review verdicts, hotspots, ownership, preflight gates, fix prompts, impact analysis, and session context. Those tools matter when they make one of the three workflows easier to verify.
28
+ 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 45-tool MCP server. The language layer uses 11 AST adapters covering 12 named languages.
27
29
 
28
- For teams, projscan can turn the workflow 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 saved time, prevented risky edits, and stayed trustworthy across real repos.
29
-
30
- 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.
31
-
32
- **Core scans run locally by default. No source upload. No projscan account or API key. `.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. Network-capable paths are explicit: `audit`, registry checks, opt-in telemetry, and optional semantic model downloads.**
33
-
34
- ```bash
35
- npx projscan
36
- ```
37
-
38
- <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">
39
-
40
- ## What's New in 4.9.2
41
-
42
- 4.9.2 is a trust patch for teams using projscan on real PRs. It reduces
43
- unused-export noise in alias-heavy and Next.js apps, makes Start proof commands
44
- explicit, and trims PR feedback prompts so reviewers can report usefulness or
45
- noise without reading a wall of instructions.
46
-
47
- - **Fewer unused-export false positives.** TypeScript path aliases, local
48
- package aliases, and Next.js App Router entrypoints now count as real usage
49
- where the framework or compiler owns the import path.
50
- - **Explicit proof commands.** Start, workplan, handoff, CLI shortcut, and MCP
51
- resume surfaces now use `projscan preflight --mode before_edit --format json`
52
- for before-edit proof instead of the ambiguous generic preflight command.
53
- - **Compact reviewer feedback.** Evidence-pack PR comments keep the Developer
54
- Feedback section, but reduce it to three actions: record usefulness, minutes
55
- saved, and noisy or false-positive signals.
56
- - **Caution triage.** Preflight cautions now separate fix-now items,
57
- review-only signals, and manual sign-off gates, which keeps release comments
58
- from treating scale review as an actual defect.
59
- - **Faster preflight input gathering.** Independent evidence collection runs in
60
- parallel where it is safe, reducing local preflight wait time without changing
61
- the report schema.
62
- - **Release verification cleanup.** The source test suite and PR-comment
63
- fixtures now validate the current compact feedback and explicit-proof
64
- behavior before publishing.
65
-
66
- <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">
67
-
68
- <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">
69
-
70
- Regenerate the README media with Playwright and VHS:
71
-
72
- ```bash
73
- npm run docs:assets
74
- npm run docs:screenshots
75
- npm run docs:demos
76
- ```
77
-
78
- ## Mission Execution Plan + Copyable Handoffs
79
-
80
- `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.
81
-
82
- 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.
83
-
84
- 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.
85
-
86
- Use the index when you want the menu, or call one shortcut directly:
30
+ ## Install
87
31
 
88
32
  ```bash
89
- projscan start --shortcuts --intent "<goal>" # Show the shortcut menu
90
- projscan start --shortcuts-json --intent "<goal>" # Shortcut menu as JSON
91
- projscan start --next-command --intent "<goal>" # Current shell command
92
- projscan start --next-tool-call --intent "<goal>" # Current MCP call as compact JSON
93
- projscan start --ready-tool-calls --intent "<goal>" # Current + proof MCP calls
94
- projscan start --proof-commands --intent "<goal>" # Remaining proof commands
95
- projscan start --checklist --intent "<goal>" # Ordered resume task card
96
- projscan start --resume-json --intent "<goal>" # Structured resume object
97
- projscan start --handoff-json --intent "<goal>" # Complete handoff object
98
- projscan start --mission-script --intent "<goal>" # Shell script: current step + proof
99
- projscan start --save-mission .projscan/mission --intent "<goal>" # Write bundle + quickstart
100
- projscan start --task-card --intent "<goal>" # Paste-ready Markdown task card
101
- projscan start --review-gate --intent "<goal>" # Stop-and-review gate
102
- projscan start --review-gate-json --intent "<goal>" # Review gate JSON
103
- projscan start --review-policy --intent "<goal>" # Review policy JSON
104
- projscan start --review-replies --intent "<goal>" # Copy-only reviewer replies
105
- projscan start --runbook --intent "<goal>" # Markdown mission runbook
106
- projscan start --handoff-prompt --intent "<goal>" # One-line handoff prompt
107
- projscan start --mission .projscan/mission # Resume from saved proof state
108
- projscan mission-proof --mission .projscan/mission --format markdown # Paste-ready proof report
109
- projscan mission-proof --list --format json # List saved mission bundles
110
- projscan mission-proof --list --needs-attention --format json # List bundles that are not passed
111
- projscan mission-proof --latest --format markdown # Report the newest saved mission bundle
112
- projscan mission-proof --all --format markdown # Roll up local saved mission bundles
113
- projscan mission-proof --all --require-passed # Fail if any selected bundle is not passed
114
- projscan mission-proof --all --summary # One-line proof status for CI logs
115
- projscan mission-proof --mission .projscan/mission --format json # Local proof summary for scripts
116
- projscan mission-proof --init-baseline manual-runs.json # Create baseline template
117
- projscan mission-proof --add-baseline-run manual-runs.json --id manual-1 --status passed --minutes-spent 25 # Record manual run
118
- projscan mission-proof --check-baseline manual-runs.json # Validate baseline file
119
- projscan mission-proof --mission .projscan/mission --write reports/mission-proof.md # Save a proof artifact
33
+ npm install -g projscan
34
+ projscan start
120
35
  ```
121
36
 
122
- Saved mission bundles include `README.md`, `next-command.txt`, `next-tool-call.json`, `handoff-prompt.txt`, `resume-prompt.txt`, `task-card.md`, `review-gate.md`, `review-gate.json`, `review-policy.json`, `review-replies.txt`, the Markdown runbook, structured handoff/resume JSON, `ready-tool-calls.json`, `shortcuts.json`, `mission.sh`, `status.sh`, `review.sh`, `proof-logs/README.md`, `proof-logs/status.jsonl`, `proof-logs/run-report.md`, `proof-logs/summary.json`, proof commands, and a manifest. The saved bundle README starts with quick commands for `./mission.sh`, `./status.sh`, and `./review.sh`; `manifest.json` exposes the same quick commands under `quickCommands` for agents and JSON clients. Running saved `mission.sh` writes current and proof command output under `proof-logs/`, appends exit codes to `status.jsonl`, refreshes `run-report.md` for review, and writes the latest run state plus next action to `summary.json` for agents. Run `./status.sh` from the bundle to print the latest mission state and next action; it exits `0` for passed, `1` for failed, and `2` for not-run or running states. Run `./review.sh` from the bundle to print the status, review gate, run report, evidence command checklist, and reviewer replies in one terminal view.
123
-
124
- When work resumes, point start at the saved bundle:
37
+ Run without a global install:
125
38
 
126
39
  ```bash
127
- projscan start --mission .projscan/mission
40
+ npx projscan start
128
41
  ```
129
42
 
130
- `projscan start` reads `proof-logs/summary.json`, `proof-logs/status.jsonl`, and local review decision files. The report tells the next agent what changed, what remains, which command failed if proof did not pass, and whether the bundle is ready for a version-candidate review. For a local measurement report, run:
43
+ Check the trust boundary first:
131
44
 
132
45
  ```bash
133
- projscan mission-proof --mission .projscan/mission --format markdown
134
- projscan mission-proof --list --format json
135
- projscan mission-proof --list --needs-attention --format json
136
- projscan mission-proof --list --mission-status failed --format json
137
- projscan mission-proof --latest --format markdown
138
- projscan mission-proof --all --format markdown
139
- projscan mission-proof --all --require-passed
140
- projscan mission-proof --all --summary --require-passed
141
- projscan mission-proof --all --write reports/mission-proof.md
142
- projscan mission-proof --mission .projscan/mission --write reports/mission-proof.md
143
- projscan mission-proof --init-baseline manual-runs.json
144
- projscan mission-proof --init-baseline manual-runs.json --format json
145
- projscan mission-proof --add-baseline-run manual-runs.json --id manual-1 --status passed --minutes-spent 25 --reruns 1 --failed-gates 0 --reviewer-approvals 1
146
- projscan mission-proof --add-baseline-run manual-runs.json --id manual-2 --status failed --format json
147
- projscan mission-proof --check-baseline manual-runs.json
148
- projscan mission-proof --check-baseline manual-runs.json --format json
149
- projscan mission-proof --mission .projscan/mission --baseline manual-runs.json --format json
150
- projscan mission-proof --mission .projscan/mission --baseline manual-runs.json --format json --write reports/mission-proof.json
151
- ```
152
-
153
- The Markdown report is ready for PR notes, release review, and handoff docs. Add `--list` to show saved mission bundles, status, update time, totals, and copyable resume/proof commands before choosing a target. Add `--needs-attention` or `--mission-status failed` to focus that list. Add `--latest` to select the saved mission bundle with the newest `proof-logs/summary.json`. Add `--all` to discover `.projscan/mission` plus direct child bundles under `.projscan/missions/`. Add `--summary` when terminal logs need one status line. Add `--require-passed` when a local script or CI job should exit nonzero unless every selected bundle passed. Add `--write reports/mission-proof.md` to save the report as a local artifact; `.md` and `.markdown` paths write Markdown by default. Use JSON when agents or scripts need the same proof data, and add `--write reports/mission-proof.json` when CI should archive it. Run `--init-baseline manual-runs.json` to create the local baseline template, then use `--add-baseline-run` to record measured manual runs without editing JSON. Add `--format json` to baseline init, append, or check commands when a wrapper needs the written path, run count, added run, or totals. If `--baseline` or `--check-baseline` points at a missing or malformed file, projscan prints the exact template command or expected JSON shape. Baseline run IDs must be non-empty and unique. Baseline run statuses must be `passed`, `failed`, `running`, `not_run`, or `unknown`; metric fields must be non-negative numbers. The baseline file is optional. When present, it can list manual runs with minutes spent, reruns, failed gates, and reviewer approvals; projscan compares that local baseline with Mission Control proof without uploading source.
154
-
155
- Default console output shows the same sections inline: `Run Cursor`, `Resume Checklist`, `Handoff Prompt`, `Ready Proof`, and `Proof Queue`. The proof views use the resume-aware remaining queue, so projscan does not repeat the current cursor command as proof.
156
-
157
- Console output shows the same model for humans:
158
-
159
- ```text
160
- Execution Plan
161
- Run 1 ready step, resolve 2 input(s), then gather 4 proof command(s).
162
- - [ready] Ready Commands
163
- - Find exact target for impact analysis: projscan search "auth token loader" --format json
164
- - [blocked] Resolve Inputs
165
- - symbol: Replace <symbol-from-search> with an exported symbol returned by the search step.
166
- - [pending] Follow Up
167
- - If search returns an exported symbol: projscan impact --symbol <symbol-from-search> --format json
168
- blocked by: input-1
169
- Run Cursor
170
- next: ready-1 in Ready Commands
171
- command: projscan search "auth token loader" --format json
172
- MCP call: projscan_search {"query":"auth token loader"}
173
- unlocks: input-1, input-2
174
- Resume Checklist
175
- - [ready] run_current ready-1: projscan search "auth token loader" --format json (MCP: projscan_search {"query":"auth token loader"})
176
- - [blocked] resolve_input input-1: <symbol-from-search> -> Replace <symbol-from-search> with an exported symbol returned by the search step.
177
- - [blocked] run_follow_up follow-up-1: projscan impact --symbol <symbol-from-search> --format json (MCP: projscan_impact {"symbol":"<symbol-from-search>"})
178
- - [ready] run_proof proof-2: projscan preflight --mode before_edit --format json (MCP: projscan_preflight {"mode":"before_edit"})
179
- Handoff Prompt
180
- Resume: Resume at ready-1 in ready_now: run `projscan search "auth token loader" --format json`. This can unlock input-1 (symbol), input-2 (file). Done when: An exact symbol or file path is selected from search results before impact analysis continues.
181
- Ready Proof
182
- Ready-to-run proof commands; placeholder follow-ups are excluded until Needs Input is resolved.
183
- - projscan preflight --mode before_edit --format json
184
- - projscan understand --view verify --format json
185
- Proof Queue
186
- - proof-2: projscan preflight --mode before_edit --format json (MCP: projscan_preflight {"mode":"before_edit"})
187
- - proof-3: projscan understand --view verify --format json (MCP: projscan_understand {"view":"verify"})
188
- ```
189
-
190
- Runbook handoff example:
191
-
192
- ````text
193
- Agent Runbook
194
- # Mission Runbook
195
- Intent: what breaks if I rename the auth token loader
196
- Status: needs_attention
197
- Current phase: ready_now
198
-
199
- ## Current Cursor
200
- - Step: ready-1 in ready_now
201
- - Command: `projscan search "auth token loader" --format json`
202
- - MCP call: projscan_search {"query":"auth token loader"}
203
- - Unlocks: input-1, input-2
204
-
205
- ## Resume
206
- Run now:
207
- ```sh
208
- projscan search "auth token loader" --format json
209
- ````
210
-
211
- MCP call: projscan_search {"query":"auth token loader"}
212
- After running, resolve:
213
-
214
- - input-1 (symbol): Replace <symbol-from-search> with an exported symbol returned by the search step.
215
- - input-2 (file): Replace <file-from-search> with a file path returned by the search step.
216
- Template inputs:
217
- - <symbol-from-search> -> input-1 (symbol): Replace <symbol-from-search> with an exported symbol returned by the search step.
218
- - <file-from-search> -> input-2 (file): Replace <file-from-search> with a file path returned by the search step.
219
- Resume checklist:
220
- - [ready] run_current ready-1: projscan search "auth token loader" --format json (MCP: projscan_search {"query":"auth token loader"})
221
- - [blocked] resolve_input input-1: <symbol-from-search> -> Replace <symbol-from-search> with an exported symbol returned by the search step.
222
- - [ready] run_proof proof-2: projscan preflight --mode before_edit --format json (MCP: projscan_preflight {"mode":"before_edit"})
223
- - [pending] confirm_done criterion-1: An exact symbol or file path is selected from search results before impact analysis continues.
224
- Proof queue:
225
- - proof-2: `projscan preflight --mode before_edit --format json` (MCP: projscan_preflight {"mode":"before_edit"})
226
- - proof-3: `projscan understand --view verify --format json` (MCP: projscan_understand {"view":"verify"})
227
- Remaining proof:
228
- - `projscan preflight --mode before_edit --format json`
229
- - `projscan understand --view verify --format json`
230
- MCP proof calls:
231
- - proof-2: projscan_preflight {"mode":"before_edit"}
232
- - proof-3: projscan_understand {"view":"verify"}
233
- Then use:
234
- - follow-up-1 (If search returns an exported symbol): projscan impact --symbol <symbol-from-search> --format json
235
- - follow-up-2 (If search returns a file path): projscan impact <file-from-search> --format json
236
- Prompt: Resume at ready-1 in ready_now: run `projscan search "auth token loader" --format json`. This can unlock input-1 (symbol), input-2 (file).
237
-
238
- ## Handoff Prompt
239
-
240
- Resume: Resume at ready-1 in ready_now: run `projscan search "auth token loader" --format json`. This can unlock input-1 (symbol), input-2 (file). Done when: An exact symbol or file path is selected from search results before impact analysis continues. Needs input: symbol=<symbol-from-search>, file=<file-from-search>. Ready proof: Ready-to-run proof commands; placeholder follow-ups are excluded until Needs Input is resolved. projscan preflight --mode before_edit --format json && projscan understand --view verify --format json.
241
-
242
- ## Review Gate
243
-
244
- - [ ] Complete this task card and remaining proof.
245
- - [ ] Capture `git status --short`.
246
- - [ ] Capture `git diff --stat`.
247
- - [ ] Stop and ask for approval before starting another slice, release, publish, or deploy.
248
-
249
- Review the completed mission, proof output, and working-tree summary before approving another slice, release, publish, or deploy.
250
-
251
- ## Ready Commands
252
-
253
- - `projscan search "auth token loader" --format json`
254
-
255
- ## Blocked Inputs
256
-
257
- - symbol: Replace <symbol-from-search> with an exported symbol returned by the search step.
258
-
259
- ````
260
-
261
- Run `projscan doctor` for a focused health check:
262
-
263
- ```bash
264
- npx projscan doctor
265
- ````
266
-
267
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/npx%20projscan%20doctor.gif" alt="npx projscan doctor" width="700">
268
-
269
- ## Install
270
-
271
- ```bash
272
- npm install -g projscan
273
- ```
274
-
275
- Or run directly without installing:
276
-
277
- ```bash
278
- npx projscan
46
+ projscan privacy-check
47
+ projscan start --intent "what can projscan read?"
48
+ projscan start --intent "does projscan read .env values?"
279
49
  ```
280
50
 
281
51
  ## Daily workflows
@@ -286,12 +56,14 @@ Use these three workflows before scanning the full command catalog.
286
56
 
287
57
  ```bash
288
58
  projscan start --intent "what files do I need to change for auth?"
59
+ projscan start --intent "what should we build next?" # Routes to a before-edit implementation workplan
289
60
  projscan understand --view change --intent "add auth token refresh" --format json
290
61
  projscan preflight --mode before_edit --format json
291
62
  ```
292
63
 
293
- Success criteria: the agent has a cited change map, likely touched files,
294
- read-first context, and a before-edit gate before it writes code.
64
+ You get a cited change map, read-first files, likely touched files, blocked inputs, and a before-edit proof gate.
65
+
66
+ Success criteria: the agent can name the files to read first, the likely files to touch, and the proof command to run before editing.
295
67
 
296
68
  ### Before handoff or commit
297
69
 
@@ -301,9 +73,9 @@ projscan preflight --mode before_commit --format json
301
73
  projscan evidence-pack --pr-comment
302
74
  ```
303
75
 
304
- Success criteria: concrete defects are separated from manual review gates, the
305
- handoff includes exact proof commands, and reviewers can see the next action
306
- without reading an agent transcript.
76
+ You get concrete fixes, manual review gates, owner routing, baseline trend memory, and exact proof commands for the reviewer.
77
+
78
+ Success criteria: the reviewer sees the top fix, the remaining proof, and any manual sign-off gate without reading the full scan output.
307
79
 
308
80
  ### Before release-candidate review
309
81
 
@@ -313,780 +85,155 @@ projscan preflight --mode before_merge --format json
313
85
  projscan evidence-pack --pr-comment
314
86
  ```
315
87
 
316
- Success criteria: release-readiness output stays read-only, `caution` explains
317
- whether the work needs fixes or manual sign-off, and no version, publish, tag,
318
- or deploy step is implied.
319
-
320
- ## Quick Start
321
-
322
- Run this path first inside a repository:
323
-
324
- ```bash
325
- projscan privacy-check # Show exactly what can be read, written, or contacted
326
- projscan start # First-60-seconds workflow orientation
327
- projscan start --intent "what can projscan read?" # Routes to local privacy/trust boundary
328
- projscan start --intent "does projscan read .env values?" # Routes to .env content policy check
329
- projscan start --intent "is it safe to commit this change?" # Mission Control: inferred mode + ready actions + done criteria + proof
330
- projscan start --intent "is my branch ready to merge?" # Routes to before-merge preflight readiness
331
- projscan start --intent "rebase went wrong" # Routes to before-merge preflight recovery
332
- projscan start --intent "resolve merge conflicts" # Routes to before-merge preflight recovery
333
- projscan start --intent "what is blocking this PR?" # Routes to before-commit preflight blockers
334
- projscan start --intent "summarize this repo" # Routes to cited repo map + orientation summary
335
- projscan start --intent "what files should I read first?" # Routes to cited repo map + read-first files
336
- projscan start --intent "where do I start in this codebase?" # Routes to cited repo map + read-first files
337
- projscan start --intent "give me a tour of the repo" # Routes to cited repo map + entrypoints
338
- projscan start --intent "explain the architecture" # Routes to cited repo map + boundaries
339
- projscan start --intent "show me the main entrypoints" # Routes to cited repo map + entrypoints
340
- projscan start --intent "how do I run this project?" # Routes to cited repo map + entrypoints
341
- projscan start --intent "what command starts the dev server?" # Routes to cited repo map + entrypoints
342
- projscan start --intent "what npm scripts exist?" # Routes to package/config contract discovery
343
- projscan start --intent "which script runs e2e tests?" # Routes to package/config contract discovery
344
- projscan start --intent "what command runs lint?" # Routes to package/config contract discovery
345
- projscan start --intent "how do I run typecheck?" # Routes to package/config contract discovery
346
- projscan start --intent "how do I seed the database?" # Routes to package/config contract discovery
347
- projscan start --intent "what command runs migrations?" # Routes to package/config contract discovery
348
- projscan start --intent "where should I put this new feature?" # Routes to change-readiness map
349
- projscan start --intent "implement OAuth login" # Routes to change-readiness map
350
- projscan start --intent "add billing webhook support" # Routes to change-readiness map
351
- projscan start --intent "build a settings page" # Routes to change-readiness map
352
- projscan start --intent "where should I add a new endpoint?" # Routes to change-readiness map
353
- projscan start --intent "what files do I need to change for auth?" # Routes to change-readiness map
354
- projscan start --intent "what docs should I update for this change?" # Routes to change-readiness map
355
- projscan start --intent "where should I add this database migration?" # Routes to change-readiness map
356
- projscan start --intent "which migrations exist?" # Routes to focused code search
357
- projscan start --intent "show me generated files" # Routes to focused code search
358
- projscan start --intent "can I drop this column?" # Routes to impact target search
359
- projscan start --intent "what are the public contracts?" # Routes to public exports/config contracts
360
- projscan start --intent "how do I safely deprecate this API?" # Routes to public exports/config contracts
361
- projscan start --intent "what will this API change break?" # Routes to impact target search
362
- projscan start --intent "what env vars does this repo need?" # Routes to config contract discovery
363
- projscan start --intent "environment variables missing" # Routes to config contract discovery
364
- projscan start --intent "where is NEXT_PUBLIC_API_URL used?" # Routes to focused code search
365
- projscan start --intent "which env var controls auth?" # Routes to focused code search
366
- projscan start --intent "where is \"Invalid token\" thrown?" # Routes to focused code search
367
- projscan start --intent "find error message \"Payment failed\"" # Routes to focused code search
368
- projscan start --intent "where is eslint config?" # Routes to focused code search
369
- projscan start --intent "which config file defines aliases?" # Routes to focused code search
370
- projscan start --intent "where is tsconfig path aliases configured?" # Routes to focused code search
371
- projscan start --intent "where is Vitest config?" # Routes to focused code search
372
- projscan start --intent "find Babel config" # Routes to focused code search
373
- projscan start --intent "where is package manager configured?" # Routes to focused code search
374
- projscan start --intent "where is pnpm workspace file?" # Routes to focused code search
375
- projscan start --intent "what is risky in this repo?" # Routes to quality dimensions + top risks
376
- projscan start --intent "what files are risky to touch?" # Routes to hotspot files
377
- projscan start --intent "which files are too complex?" # Routes to hotspot files
378
- projscan start --intent "what file should I refactor first?" # Routes to hotspot files
379
- projscan start --intent "what tech debt should I pay down?" # Routes to hotspot files
380
- projscan start --intent "what code should I simplify?" # Routes to hotspot files
381
- projscan start --intent "find performance bottlenecks" # Routes to hotspot files
382
- projscan start --intent "where are the slow files?" # Routes to hotspot files
383
- projscan start --intent "find dead code" # Routes to doctor cleanup issues
384
- projscan start --intent "find dead code and unused exports I can delete" # Routes to doctor cleanup issues
385
- projscan start --intent "what can I safely delete?" # Routes to doctor cleanup discovery
386
- projscan start --intent "what can I remove safely?" # Routes to doctor cleanup discovery
387
- projscan start --intent "port 3000 already in use" # Routes to focused regression planning
388
- projscan start --intent "peer dependency conflict after npm install" # Routes to focused regression planning
389
- projscan start --intent "where is runAudit used?" # Routes to symbol impact/caller analysis
390
- projscan start --intent "what code handles billing?" # Routes to focused code search
391
- projscan start --intent "which file contains checkout logic?" # Routes to focused code search
392
- projscan start --intent "find the Stripe webhook handler" # Routes to focused code search
393
- projscan start --intent "find the handler for POST /api/users" # Routes to focused code search
394
- projscan start --intent "where is the /checkout route handled?" # Routes to focused code search
395
- projscan start --intent "where is /settings page rendered?" # Routes to focused code search
396
- projscan start --intent "which page renders /billing?" # Routes to focused code search
397
- projscan start --intent "where is route segment for dashboard?" # Routes to focused code search
398
- projscan start --intent "where is not-found page handled?" # Routes to focused code search
399
- projscan start --intent "which feature flags exist?" # Routes to focused code search
400
- projscan start --intent "what background jobs exist?" # Routes to focused code search
401
- projscan start --intent "find the email queue processor" # Routes to focused code search
402
- projscan start --intent "where are metrics emitted?" # Routes to focused code search
403
- projscan start --intent "where do we initialize Sentry?" # Routes to focused code search
404
- projscan start --intent "what logs should I check for checkout?" # Routes to focused code search
405
- projscan start --intent "find the dashboard for payments" # Routes to focused code search
406
- projscan start --intent "where is seed data defined?" # Routes to focused code search
407
- projscan start --intent "find fixtures for checkout" # Routes to focused code search
408
- projscan start --intent "which mocks are used for payments?" # Routes to focused code search
409
- projscan start --intent "where are Storybook stories for Button?" # Routes to focused code search
410
- projscan start --intent "where are permissions checked for checkout?" # Routes to focused code search
411
- projscan start --intent "which role can access admin?" # Routes to focused code search
412
- projscan start --intent "what routes require login?" # Routes to focused code search
413
- projscan start --intent "where is rate limiting configured?" # Routes to focused code search
414
- projscan start --intent "where is cache invalidated for products?" # Routes to focused code search
415
- projscan start --intent "find retry logic for payments" # Routes to focused code search
416
- projscan start --intent "what sets request timeout?" # Routes to focused code search
417
- projscan start --intent "find idempotency key handling" # Routes to focused code search
418
- projscan start --intent "where is webhook signature verified?" # Routes to focused code search
419
- projscan start --intent "where is input validation for signup?" # Routes to focused code search
420
- projscan start --intent "which schema validates checkout?" # Routes to focused code search
421
- projscan start --intent "where are request params parsed?" # Routes to focused code search
422
- projscan start --intent "where is database transaction started?" # Routes to focused code search
423
- projscan start --intent "where do we lock the order row?" # Routes to focused code search
424
- projscan start --intent "what validates email uniqueness?" # Routes to focused code search
425
- projscan start --intent "where is Prisma model for User?" # Routes to focused code search
426
- projscan start --intent "find Drizzle schema for invoices" # Routes to focused code search
427
- projscan start --intent "where is SQL query for invoices?" # Routes to focused code search
428
- projscan start --intent "which repository saves orders?" # Routes to focused code search
429
- projscan start --intent "find DAO for payments" # Routes to focused code search
430
- projscan start --intent "where is loading state for dashboard?" # Routes to focused code search
431
- projscan start --intent "where is error boundary for settings?" # Routes to focused code search
432
- projscan start --intent "find command palette actions" # Routes to focused code search
433
- projscan start --intent "where are i18n translations for checkout?" # Routes to focused code search
434
- projscan start --intent "where are design tokens defined?" # Routes to focused code search
435
- projscan start --intent "where is Tailwind theme configured?" # Routes to focused code search
436
- projscan start --intent "where is global CSS imported?" # Routes to focused code search
437
- projscan start --intent "which CSS module styles Button?" # Routes to focused code search
438
- projscan start --intent "where is dark mode configured?" # Routes to focused code search
439
- projscan start --intent "what breakpoints are defined?" # Routes to focused code search
440
- projscan start --intent "where is sidebar nav item for billing?" # Routes to focused code search
441
- projscan start --intent "which breadcrumb renders settings?" # Routes to focused code search
442
- projscan start --intent "where is page title set for checkout?" # Routes to focused code search
443
- projscan start --intent "where is Next.js layout for dashboard?" # Routes to focused code search
444
- projscan start --intent "where is auth state stored?" # Routes to focused code search
445
- projscan start --intent "find Redux slice for cart" # Routes to focused code search
446
- projscan start --intent "where is Zustand store for user settings?" # Routes to focused code search
447
- projscan start --intent "which context provider supplies theme?" # Routes to focused code search
448
- projscan start --intent "which hook fetches invoices?" # Routes to focused code search
449
- projscan start --intent "where is React Query mutation for checkout?" # Routes to focused code search
450
- projscan start --intent "where do we call Stripe?" # Routes to focused code search
451
- projscan start --intent "which code sends email through SendGrid?" # Routes to focused code search
452
- projscan start --intent "where is S3 upload implemented?" # Routes to focused code search
453
- projscan start --intent "find GitHub API client" # Routes to focused code search
454
- projscan start --intent "where is GraphQL query for invoices?" # Routes to focused code search
455
- projscan start --intent "where is websocket connection opened?" # Routes to focused code search
456
- projscan start --intent "where is OpenAPI spec defined?" # Routes to focused code search
457
- projscan start --intent "where is Swagger docs configured?" # Routes to focused code search
458
- projscan start --intent "where is tRPC router for billing?" # Routes to focused code search
459
- projscan start --intent "which GraphQL resolver handles invoices?" # Routes to focused code search
460
- projscan start --intent "which protobuf defines user service?" # Routes to focused code search
461
- projscan start --intent "where is gRPC client for payments?" # Routes to focused code search
462
- projscan start --intent "where is the Dockerfile?" # Routes to focused code search
463
- projscan start --intent "where is docker compose for local dev?" # Routes to focused code search
464
- projscan start --intent "where are Kubernetes manifests?" # Routes to focused code search
465
- projscan start --intent "find Helm chart for payments" # Routes to focused code search
466
- projscan start --intent "where is Terraform module for S3?" # Routes to focused code search
467
- projscan start --intent "which GitHub workflow deploys staging?" # Routes to focused code search
468
- projscan start --intent "where is Vercel config?" # Routes to focused code search
469
- projscan start --intent "where is password reset handled?" # Routes to focused code search
470
- projscan start --intent "where is team invite flow?" # Routes to focused code search
471
- projscan start --intent "where is onboarding flow implemented?" # Routes to focused code search
472
- projscan start --intent "find CSV export for users" # Routes to focused code search
473
- projscan start --intent "what creates audit log entries?" # Routes to focused code search
474
- projscan start --intent "where is refund handling for payments?" # Routes to focused code search
475
- projscan start --intent "where is subscription renewal handled?" # Routes to focused code search
476
- projscan start --intent "where is welcome email template?" # Routes to focused code search
477
- projscan start --intent "find password reset email copy" # Routes to focused code search
478
- projscan start --intent "where is push notification copy for invites?" # Routes to focused code search
479
- projscan start --intent "where is SMS verification template?" # Routes to focused code search
480
- projscan start --intent "which template sends receipt email?" # Routes to focused code search
481
- projscan start --intent "where is invoice PDF generated?" # Routes to focused code search
482
- projscan start --intent "find documentation for auth" # Routes to focused docs search
483
- projscan start --intent "what depends on src/core/start.ts?" # Routes to file impact/dependency analysis
484
- projscan start --intent "can I delete src/core/start.ts?" # Routes to file impact/dependency analysis
485
- projscan start --intent "revert src/core/start.ts safely" # Routes to file impact/dependency analysis
486
- projscan start --intent "how do I revert this change safely?" # Routes to impact target search
487
- projscan start --intent "what dependencies does this repo use?" # Routes to dependency inventory
488
- projscan start --intent "why is the bundle so large?" # Routes to dependency size inventory
489
- projscan start --intent "find package bloat" # Routes to dependency size inventory
490
- projscan start --intent "what licenses do our dependencies use?" # Routes to dependency license inventory
491
- projscan start --intent "who uses lodash?" # Routes to package importer graph query
492
- projscan start --intent "why do we depend on lodash?" # Routes to package importer graph query
493
- projscan start --intent "third party notices" # Routes to dependency license inventory
494
- projscan start --intent "open source compliance check" # Routes to dependency license inventory
495
- projscan start --intent "what workspaces are in this repo?" # Routes to monorepo workspace map
496
- projscan start --intent "which workspace owns auth?" # Routes to monorepo workspace map
497
- projscan start --intent "where should I put this in the monorepo?" # Routes to monorepo workspace map
498
- projscan start --intent "does lodash have a CVE?" # Routes to scoped npm audit
499
- projscan start --intent "what CVEs affect this repo?" # Routes to npm audit
500
- projscan start --intent "find vulnerable packages" # Routes to npm audit
501
- projscan start --intent "who owns auth?" # Routes to focused ownership search
502
- projscan start --intent "which team owns payments?" # Routes to focused ownership search
503
- projscan start --intent "who should I ask about auth?" # Routes to focused ownership search
504
- projscan start --intent "what should I read before changing src/core/start.ts?" # Routes to exact-file orientation
505
- projscan start --intent "explain src/core/start.ts" # Routes to per-file purpose/risk/ownership inspection
506
- projscan start --intent "who owns src/core/start.ts?" # Routes to file ownership/risk context
507
- projscan start --intent "who should review src/core/start.ts?" # Routes to file ownership/reviewer context
508
- projscan start --intent "who last touched src/core/start.ts?" # Routes to file ownership/history context
509
- projscan start --intent "why is src/core/start.ts risky?" # Routes to exact-file risk context
510
- projscan start --intent "who imports src/core/start.ts?" # Routes to a targeted semantic graph query
511
- projscan start --intent "where are the tests for src/core/start.ts?" # Routes to focused test-file search
512
- projscan start --intent "where are tests for auth?" # Routes to focused test-topic search
513
- projscan start --intent "which tests cover auth?" # Routes to focused existing-test search
514
- projscan start --intent "locate specs for checkout" # Routes to focused test-topic search
515
- projscan start --intent "which tests should I run for src/core/start.ts?" # Routes to verification proof planning
516
- projscan start --intent "what should I test before pushing?" # Routes to verification proof planning
517
- projscan start --intent "is src/core/start.ts covered by tests?" # Routes to file coverage/risk context
518
- projscan start --intent "what tests should I add for src/core/start.ts?" # Routes to file test-design context
519
- projscan start --intent "what changed in this PR?" # Routes to structural PR diff
520
- projscan start --intent "is this PR too large?" # Routes to structural PR diff
521
- projscan start --intent "what did I change since main?" # Routes to structural branch diff
522
- projscan start --intent "is my branch stale?" # Routes to structural branch diff
523
- projscan start --intent "compare my branch with main" # Routes to structural branch diff
524
- projscan start --intent "write a commit message for these changes" # Routes to structural diff evidence
525
- projscan start --intent "summarize my changes for a commit" # Routes to structural diff evidence
526
- projscan start --intent "how risky is this PR?" # Routes to structural PR review
527
- projscan start --intent "what are the risks in my PR?" # Routes to structural PR review
528
- projscan start --intent "what are the top risks before merge?" # Routes to before-merge preflight readiness
529
- projscan start --intent "am I ready to open a PR?" # Routes to PR-readiness evidence pack
530
- projscan start --intent "who should review this PR?" # Routes to owner-routing evidence pack
531
- projscan start --intent "who owns the changed files?" # Routes to changed-file owner routing
532
- projscan start --intent "write a PR comment for reviewers" # Routes to approval-ready evidence pack
533
- projscan start --intent "write a PR description" # Routes to approval-ready evidence pack
534
- projscan start --intent "what should my PR say?" # Routes to approval-ready evidence pack
535
- projscan start --intent "make a PR checklist" # Routes to approval-ready evidence pack
536
- projscan start --intent "what should I tell my team about this change?" # Routes to approval-ready evidence pack
537
- projscan start --intent "what should I fix first?" # Routes to bug-hunt prioritization
538
- projscan start --intent "what is the fastest safe fix?" # Routes to bug-hunt prioritization before generic safety
539
- projscan start --intent "find a quick win" # Routes to bug-hunt prioritization
540
- projscan start --intent "what can I do in five minutes?" # Routes to bug-hunt prioritization
541
- projscan start --intent "pick an easy task for me" # Routes to bug-hunt prioritization
542
- projscan start --intent "what should an intern work on?" # Routes to bug-hunt prioritization
543
- projscan start --intent "what is a low risk improvement?" # Routes to bug-hunt prioritization
544
- projscan start --intent "pick a small safe task" # Routes to bug-hunt prioritization
545
- projscan start --intent "what should I do next?" # Routes to an ordered before-edit workplan
546
- projscan start --intent "what should we build next?" # Routes to a before-edit implementation workplan
547
- projscan start --intent "explain issue missing-test-framework" # Routes to deep issue context
548
- projscan start --intent "fix issue missing-test-framework" # Routes to a concrete fix suggestion
549
- projscan start --intent "is user input reaching SQL sinks?" # Routes to hardening dataflow analysis
550
- projscan start --intent "does this endpoint expose secrets?" # Routes to hardening dataflow analysis
551
- projscan start --intent "where is PII handled?" # Routes to hardening dataflow analysis
552
- projscan start --intent "GDPR compliance check" # Routes to hardening dataflow analysis
553
- projscan start --intent "where do we store access tokens?" # Routes to hardening dataflow analysis
554
- projscan start --intent "is this change secure?" # Routes to structural PR review
555
- projscan start --intent "check this PR for security issues" # Routes to structural PR review
556
- projscan start --intent "what are the scariest untested files?" # Routes to coverage × hotspot test targets
557
- projscan start --intent "which files have no tests?" # Routes to coverage × hotspot test targets
558
- projscan start --intent "what breaks if I bump chalk to 6?" # Routes to offline package upgrade impact
559
- projscan start --intent "what breaks if I update react?" # Routes to offline package upgrade impact
560
- projscan start --intent "can I remove lodash?" # Routes to offline package removal impact
561
- projscan start --intent "is lodash safe to remove?" # Routes to offline package removal impact
562
- projscan start --intent "CI is failing after this PR" # Routes to a focused regression plan
563
- projscan start --intent "CI is flaky" # Routes to a focused regression plan
564
- projscan start --intent "production is down" # Routes to a focused regression plan
565
- projscan start --intent "why is the login endpoint returning 500?" # Routes to a focused regression plan
566
- projscan start --intent "why did CI fail?" # Routes to a focused regression plan
567
- projscan start --intent "why is GitHub Actions failing?" # Routes to a focused regression plan
568
- projscan start --intent "which GitHub Actions job failed?" # Routes to a focused regression plan
569
- projscan start --intent "why is CI slow?" # Routes to a focused regression plan
570
- projscan start --intent "why did the build fail?" # Routes to a focused regression plan
571
- projscan start --intent "what is making builds slow?" # Routes to a focused regression plan
572
- projscan start --intent "lint is failing" # Routes to a focused regression plan
573
- projscan start --intent "typecheck is failing" # Routes to a focused regression plan
574
- projscan start --intent "npm install is failing" # Routes to a focused regression plan
575
- projscan start --intent "debug this stack trace" # Routes to a focused regression plan
576
- projscan start --intent "where is this stack trace from?" # Routes to a focused regression plan
577
- projscan start --intent "database connection refused locally" # Routes to a focused regression plan
578
- projscan start --intent "what command reproduces the flake?" # Routes to a focused regression plan
579
- projscan start --intent "quarantine flaky test" # Routes to a focused regression plan
580
- projscan start --intent "what tests should I run for my changes?" # Routes to verification proof planning
581
- projscan start --intent "how can I speed up tests?" # Routes to a focused regression plan
582
- projscan start --intent "what commands prove this works?" # Routes to focused proof commands
583
- projscan start --intent "what commands benchmark this repo?" # Routes to focused proof commands
584
- projscan start --intent "give me proof commands" # Routes to focused proof commands
585
- projscan start --intent "what commands should I run before pushing?" # Routes to focused pre-push proof
586
- projscan start --intent "what smoke checks should I run before commit?" # Routes to a smoke regression plan
587
- projscan start --intent "what full regression should I run before merge?" # Routes to a full regression plan
588
- projscan start --intent "what should I check before release?" # Routes to release readiness
589
- projscan start --intent "can I deploy this?" # Routes to release readiness
590
- projscan start --intent "what changed since last release?" # Routes to release readiness
591
- projscan start --intent "write a release note for this change" # Routes to release readiness and changelog evidence
592
- projscan start --intent "draft changelog entry" # Routes to release readiness and changelog evidence
593
- projscan start --intent "show coordination status for parallel agents" # Routes to one-call swarm readiness
594
- projscan start --intent "who else is working on this?" # Routes to one-call swarm readiness
595
- projscan start --intent "am I going to collide with another agent?" # Routes to one-call swarm readiness
596
- projscan start --intent "what worktrees are active?" # Routes to one-call swarm readiness
597
- projscan start --intent "what should merge first?" # Routes to merge-risk ordering
598
- projscan start --intent "show me overlapping changes" # Routes to collision detection
599
- projscan start --intent "show active claims" # Routes to advisory claim listing
600
- projscan start --intent "claim src/core/start.ts for me" # Routes to active-claim review + file claim action
601
- projscan start --intent "where did I leave off?" # Routes to touched-file session context
602
- projscan start --intent "what changed while I was away?" # Routes to touched-file session context
603
- projscan start --intent "what changed while I was offline?" # Routes to touched-file session context
604
- projscan start --intent "what changed while I was asleep?" # Routes to touched-file session context
605
- projscan start --intent "what did the last agent touch?" # Routes to remembered touched-file session context
606
- projscan start --intent "what did the last agent do?" # Routes to remembered touched-file session context
607
- projscan start --intent "give the next agent a handoff" # Routes to a compact agent brief
608
- projscan understand --view map # Cited repo map, flows, contracts, change readiness, and verification proof
609
- projscan preflight --format json # Proceed/caution/block safety gate
610
- projscan evidence-pack --pr-comment # Reviewer-ready PR evidence
611
- ```
612
-
613
- For MCP clients:
88
+ You get read-only readiness evidence. projscan reports fixes and sign-off gates; it does not tag, publish, deploy, or bump versions from these commands.
614
89
 
615
- ```bash
616
- projscan first-run
617
- projscan init mcp --client all
618
- projscan mcp doctor --client codex
619
- projscan mcp
620
- ```
90
+ Success criteria: release review separates concrete defects from human approval gates before anyone tags or publishes.
621
91
 
622
- For team rollout after the first local run is trusted:
92
+ ## Mission Control
623
93
 
624
- ```bash
625
- projscan init team --team security
626
- projscan telemetry explain
627
- projscan feedback init --output .projscan-feedback.json
628
- projscan dogfood --repo ../api --repo ../web --repo ../worker --feedback .projscan-feedback.json --format json
629
- projscan trial --repo ../api --repo ../web --repo ../worker --feedback .projscan-feedback.json --format json
630
- ```
94
+ `projscan start --intent "<goal>"` turns a plain-language goal into an execution plan:
631
95
 
632
- For copyable team recipes, see
633
- [`docs/examples/swarm-coordination.md`](docs/examples/swarm-coordination.md)
634
- and [`docs/examples/adoption-workflows.md`](docs/examples/adoption-workflows.md).
96
+ - current command
97
+ - blocked inputs
98
+ - follow-up commands
99
+ - proof queue
100
+ - done criteria
101
+ - review gate
635
102
 
636
- For maintainers changing trust-sensitive behavior:
103
+ Save a mission when work may pass between agents:
637
104
 
638
105
  ```bash
639
- npm run test:trust-smoke
106
+ projscan start --save-mission .projscan/mission --intent "is it safe to commit this change?"
107
+ projscan mission-proof --mission .projscan/mission --format markdown
108
+ projscan start --mission .projscan/mission
640
109
  ```
641
110
 
642
- The full command catalog is below. Most users should start with the daily workflows above instead of scanning the catalog.
111
+ <img src="docs/projscan-proof-router.png" alt="projscan proof workflow showing mission proof, MCP resume input, proof summary, and version review gate" width="760">
643
112
 
644
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/npx%20projscan%20--help.gif" alt="npx projscan --help" width="700">
113
+ Mission bundles include a runbook, task card, handoff prompt, proof scripts, review gate JSON, reviewer replies, and proof logs. `mission-proof` summarizes passed proof, failed gates, reruns, reviewer decisions, and optional manual baseline data.
645
114
 
646
- For a comprehensive walkthrough, see the **[Full Guide](https://github.com/abhiyoheswaran1/projscan/blob/v4.3.1/docs/GUIDE.md)**.
115
+ <details>
116
+ <summary><strong>Terminal demos</strong></summary>
647
117
 
648
- ## Repo Understanding
118
+ <img src="docs/projscan-mission-control.gif" alt="projscan start printing shortcut commands for a safe-commit intent" width="760">
649
119
 
650
- Use `projscan understand` before a real edit when the question is broader than one file. It gives engineers and agents a cited map of the repo instead of a loose summary.
120
+ <img src="docs/projscan-mission-proof.gif" alt="projscan saving a mission, reporting proof status, and printing the review gate" width="760">
651
121
 
652
- ```bash
653
- projscan understand --view map --format json
654
- projscan understand --view flow --format json
655
- projscan understand --view contracts --format json
656
- projscan understand --view change --intent "rename auth token loader" --format json
657
- projscan understand --view verify --format json
658
- ```
122
+ </details>
659
123
 
660
- The report includes file/symbol-backed `claims`, `readFirst` files, entrypoints, package boundaries, runtime flows, public exports, config contracts, breaking-change risks, change readiness, verification tiers, unknowns, and exact next commands.
661
-
662
- ## Commands
663
-
664
- | Command | Description |
665
- | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
666
- | `projscan analyze` | Full analysis - languages, frameworks, dependencies, issues |
667
- | `projscan route` | Map a plain-language goal to the best projscan tool with weighted confidence and matched keywords |
668
- | `projscan start` | First-60-seconds workflow orientation with daily workflows, setup diagnostics, Mission Control, top risks, and next commands. Add `--intent "<goal>"` to route a plain-language goal to route confidence, phased execution plan, ready actions, done criteria, and proof commands |
669
- | `projscan mission-proof` | Summarize saved Mission Control proof, reviewer decisions, reruns, failed gates, and optional manual-baseline comparison |
670
- | `projscan first-run` | First-run setup diagnostics plus the shared `firstTenMinutes` command path |
671
- | `projscan init mcp` | Ready-to-paste MCP client configs for popular agent clients |
672
- | `projscan mcp doctor` | Verify MCP setup and print paste-ready client config with checks |
673
- | `projscan init policy` | Team policy starter kits for frontend, platform, security, and monorepo teams |
674
- | `projscan init team` | Bootstrap policy, PR workflow, CODEOWNERS starter, baseline memory, start report, and first-PR onboarding checklist |
675
- | `projscan init github-action` | GitHub Actions PR workflow that validates and posts projscan evidence comments, then fails only on preflight blocks |
676
- | `projscan recipes` | Agent workflow recipes for team bootstrap, PR automation, before edit, bug hunt, approval, handoff, and pre-merge |
677
- | `projscan workplan` | Agent execution plan - prioritized tasks with evidence, tools, verification, and handoff text |
678
- | `projscan bug-hunt` | Prioritized bug-hunt action queue from doctor, preflight, and session evidence; manual sign-off-only queues print review wording while JSON verdict compatibility is preserved, and hotspot-only churn stays as a watchlist signal |
679
- | `projscan agent-brief` | Compact next-agent context packet with focus items, coordination hints, guardrails, repo context, and next actions |
680
- | `projscan quality-scorecard` | Dimensioned quality view with health, security, tests, maintainability, coordination, and top risks |
681
- | `projscan understand` | Cited repo map, runtime flows, public contracts, change readiness, verification tiers, unknowns, and next commands |
682
- | `projscan release-train` | Plan upcoming product lines with readiness evidence |
683
- | `projscan evidence-pack` | Assemble approval evidence from planning, bug-hunt, workplan, preflight, trust calibration, First Fix, owner routing, and baseline trend memory |
684
- | `projscan trial` | Produce one adoption-readiness report from onboarding, dogfood, feedback, trust signals, and website proof |
685
- | `projscan feedback` | Capture measured reviewer feedback: minutes saved, prevented bad edits, false positives, and repeat PR use |
686
- | `projscan privacy-check` | Verify the local trust boundary: telemetry, offline mode, scan root, .gitignore handling, ignored-file count, .env content scanning, and network-capable endpoints |
687
- | `projscan telemetry` | Explicit default-off telemetry controls: status, enable, disable, and explain |
688
- | `projscan dogfood` | Evaluate 1+ real repos for PR-comment readiness, repeat-use readiness, MCP readiness, and reviewer feedback prompts |
689
- | `projscan regression-plan` | Build a smoke, focused, or full regression matrix from product risk signals |
690
- | `projscan handoff` | Concise next-agent handoff from the current workplan |
691
- | `projscan doctor` | Health check - missing tooling, architecture smells, security and supply-chain risks |
692
- | `projscan preflight` | Agent safety gate - `proceed`, `caution`, or `block` with health, change, plugin, and supply-chain evidence |
693
- | `projscan hotspots` | Rank files by risk - churn × complexity × issues × ownership |
694
- | `projscan semantic-graph` | Stable v3 graph contract, plus targeted `--query importers/imports/exports/...` lookups |
695
- | `projscan dataflow` | Focused direct, propagated, and bridge source-to-sink dataflow risks |
696
- | `projscan search <query>` | **BM25-ranked search** - content + symbols + path, with excerpts |
697
- | `projscan file <path>` | Drill into a file - purpose, risk, ownership, related issues |
698
- | `projscan fix` | Auto-fix issues (ESLint, Prettier, Vitest, .editorconfig) |
699
- | `projscan ci` | CI health gate - SARIF output, `--changed-only` PR-diff mode, exits 1 if score below threshold |
700
- | `projscan diff` | Compare current health **and hotspot trends** against a baseline |
701
- | `projscan diagram` | ASCII architecture diagram of your project |
702
- | `projscan structure` | Directory tree with file counts |
703
- | `projscan dependencies` | Dependency analysis - counts, license summary, risks, recommendations |
704
- | `projscan outdated` | Declared-vs-installed drift check (offline) |
705
- | `projscan audit` | `npm audit`-powered vulnerability report - SARIF-ready for Code Scanning |
706
- | `projscan upgrade <pkg>` | Preview upgrade impact - npm CHANGELOG/importers or Python manifest, lockfile, and importer evidence, offline by default |
707
- | `projscan coverage` | **Coverage × hotspots - rank the scariest untested files** (`--changed-only` for diff mode) |
708
- | `projscan badge` | Generate a health score badge for your README |
709
- | `projscan init` | _(1.6)_ Scaffold `.projscanrc.json` with sensible defaults |
710
- | `projscan install-hook` | _(1.6)_ Install a `pre-commit` hook running `projscan ci --changed-only` |
711
- | `projscan workspace` | _(1.6)_ Register sibling repos for cross-repo intelligence (`add` / `list` / `remove`) |
712
- | `projscan apply-fix <id>` | _(1.6)_ Mechanically execute the safe fix templates with rollback (default dry-run) |
713
- | `projscan taint` | _(1.6)_ Source-to-sink reachability over the call graph |
714
- | `projscan plugin` | Discover, scaffold, validate, and test local analyzer/reporter plugins |
715
- | `projscan mcp` | Run as an MCP server for AI coding agents (Claude Code, Codex, Cursor, Gemini, Windsurf, …) |
716
-
717
- To see all commands and options, run:
124
+ Regenerate README media:
718
125
 
719
126
  ```bash
720
- projscan --help
127
+ npm run docs:screenshots
128
+ npm run docs:demos
721
129
  ```
722
130
 
723
- ### Command Screenshots
724
-
725
- <details>
726
- <summary><strong>projscan structure</strong> - Directory tree with file counts</summary>
727
-
728
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/npx%20projscan%20structure.gif" alt="npx projscan structure" width="700">
729
- </details>
730
-
731
- <details>
732
- <summary><strong>projscan diagram</strong> - Architecture visualization</summary>
733
-
734
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/npx%20projscan%20diagram.gif" alt="npx projscan diagram" width="700">
735
- </details>
736
-
737
- <details>
738
- <summary><strong>projscan dependencies</strong> - Dependency analysis</summary>
131
+ ## 4.9.3 Notes
739
132
 
740
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/npx%20projscan%20dependencies.gif" alt="npx projscan dependencies" width="700">
741
- </details>
133
+ 4.9.3 is a documentation and proof-media patch for the 4.9 trust release:
742
134
 
743
- <details>
744
- <summary><strong>projscan badge</strong> - Health badge generation</summary>
135
+ - README now starts with install, three daily workflows, MCP setup, command map, and the trust model.
136
+ - Mission Control screenshots and VHS demos were regenerated from current CLI output.
137
+ - The release keeps the 4.9.2 runtime fixes for TypeScript aliases, local package aliases, Next.js App Router entrypoints, explicit before-edit proof, compact reviewer feedback, caution triage, and parallel preflight gathering.
745
138
 
746
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/npx%20projscan%20badge.gif" alt="npx projscan badge" width="700">
747
- </details>
139
+ ## MCP Setup
748
140
 
749
- ### Output Formats
141
+ Use MCP when an agent should call projscan during a coding session.
750
142
 
751
- Commands accept `--format` for different output targets. Supported formats are command-dependent; unsupported combinations fail clearly instead of falling back to another renderer.
143
+ Claude Code:
752
144
 
753
145
  ```bash
754
- projscan analyze --format json # Machine-readable JSON
755
- projscan analyze --format html # Self-contained HTML report
756
- projscan doctor --format markdown # Markdown for docs/PRs
757
- projscan mission-proof --format markdown # Mission proof report for handoffs
758
- projscan mission-proof --write reports/mission-proof.md # Save Markdown proof
759
- projscan ci --format sarif # SARIF 2.1.0 for GitHub Code Scanning
760
- projscan analyze --report-scope src/api --redact-paths --format json # Scoped, redacted shareable evidence
761
- projscan analyze --report-scope "src/api,packages/backend" --redact-paths --format json # Multi-scope partner evidence
762
- projscan doctor --report-policy apiEvidence --format markdown # Reuse a configured evidence policy
146
+ claude mcp add projscan -- npx -y projscan mcp
763
147
  ```
764
148
 
765
- Formats: `console` (default), `json`, `markdown`, `sarif`, `html`
149
+ Codex CLI:
766
150
 
767
- `analyze`, `doctor`, and `ci` also accept `--report-policy <name>`,
768
- `--report-scope <paths>`, and `--redact-paths` for shareable evidence artifacts.
769
- Scope is comma-separated and repo-relative; redaction replaces file paths with
770
- stable labels. JSON/SARIF include path-safe `reportControls` metadata, and
771
- Markdown/HTML print path-safe controls banners. Direct `--report-scope` and
772
- `--redact-paths` flags override the selected preset for a single run.
773
-
774
- Run `projscan help` for the generated command-by-command support matrix.
775
-
776
- ### Plugin Platform
777
-
778
- projscan can load local plugins from `.projscan-plugins/` when `PROJSCAN_PLUGINS_PREVIEW=1` is set. The environment flag is kept for explicit local-code opt-in. Analyzer plugins emit normal projscan issues; reporter plugins render supported CLI commands with team-specific output.
151
+ ```toml
152
+ [mcp_servers.projscan]
153
+ command = "npx"
154
+ args = ["-y", "projscan", "mcp"]
155
+ ```
779
156
 
780
- **2.0 upgrade notes:** migrating from 1.x or authoring plugins? Start with the [2.0 Migration Guide](https://github.com/abhiyoheswaran1/projscan/blob/v4.3.1/docs/2.0-MIGRATION.md), then use [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v4.3.1/docs/PLUGIN-AUTHORING.md), the [Plugin Gallery](https://github.com/abhiyoheswaran1/projscan/blob/v4.3.1/docs/PLUGIN-GALLERY.md), and the [manifest schema](https://github.com/abhiyoheswaran1/projscan/blob/v4.3.1/docs/plugin.schema.json) as the stable contract.
157
+ Cursor, Windsurf, Cline, Continue, Zed, and other MCP clients can launch the same command:
781
158
 
782
159
  ```bash
783
- projscan plugin list
784
- projscan plugin validate .projscan-plugins/team-radar.projscan-plugin.json
785
- projscan plugin test .projscan-plugins/team-radar.projscan-plugin.json
786
- PROJSCAN_PLUGINS_PREVIEW=1 projscan plugin test .projscan-plugins/team-radar.projscan-plugin.json --execute
787
- PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-radar
788
- PROJSCAN_PLUGINS_PREVIEW=1 projscan ci --reporter team-radar --min-score 80
160
+ npx -y projscan mcp
789
161
  ```
790
162
 
791
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/projscan-reporter-plugin.gif" alt="projscan local reporter plugin rendering a team health report" width="700">
792
-
793
- Reporter plugins are intentionally CLI-only. MCP tools keep returning structured JSON-compatible payloads so agents can reason over stable data, while humans can get a polished local report for their team. Custom presentation, team-branded summaries, and white-label reports belong in reporter plugins rather than new core HTML theming flags. See [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v4.3.1/docs/PLUGIN-AUTHORING.md) for manifest shape, `render(context)`, validation, and the trust model.
794
-
795
- ### Options
796
-
797
- | Flag | Description |
798
- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
799
- | `--format <type>` | Output format: console, json, markdown, sarif, html (command-dependent) |
800
- | `--config <path>` | Path to a `.projscanrc` config file |
801
- | `--include-ignored` | Explicitly include files hidden by Git ignore rules |
802
- | `--scan-env-values` | Explicitly read `.env*` contents during secret checks |
803
- | `--offline` | Block projscan network-capable features for this run |
804
- | `--shortcuts` | Print the Mission Control shortcut command index (`start`) |
805
- | `--shortcuts-json` | Print the Mission Control shortcut command index as JSON (`start`) |
806
- | `--handoff-prompt` | Print only the concise Mission Control handoff prompt (`start`) |
807
- | `--next-command` | Print only the current Mission Control cursor command (`start`) |
808
- | `--next-tool-call` | Print only the current Mission Control cursor MCP tool call as JSON (`start`) |
809
- | `--ready-tool-calls` | Print the current cursor and remaining MCP-callable proof queue as JSON (`start`) |
810
- | `--proof-commands` | Print only ready Mission Control proof commands (`start`) |
811
- | `--checklist` | Print only the Mission Control resume checklist (`start`) |
812
- | `--resume-json` | Print only the Mission Control resume object as JSON (`start`) |
813
- | `--handoff-json` | Print only the Mission Control handoff object as JSON (`start`) |
814
- | `--mission-script` | Print the Mission Control shell script (`start`) |
815
- | `--save-mission <dir>` | Write the Mission Control bundle to a directory (`start`) |
816
- | `--mission <dir>` | Read a saved Mission Control bundle and include proof outcome in `start`; repeatable mission selector for `mission-proof` |
817
- | `--list` | List saved Mission Control bundles with status and update time (`mission-proof`) |
818
- | `--needs-attention` | Filter `mission-proof --list` to bundles that are not passed |
819
- | `--mission-status <status>` | Filter `mission-proof --list` by `passed`, `failed`, `running`, `not_run`, or `unknown` |
820
- | `--latest` | Select the saved Mission Control bundle with the newest `proof-logs/summary.json` (`mission-proof`) |
821
- | `--all` | Discover `.projscan/mission` and direct child bundles under `.projscan/missions/` (`mission-proof`) |
822
- | `--baseline <path>` | Compare `mission-proof` with a local manual-run baseline JSON file |
823
- | `--init-baseline <file>` | Write a local manual-run baseline JSON template (`mission-proof`) |
824
- | `--add-baseline-run <file>` | Append one measured manual run to a local baseline JSON file (`mission-proof`) |
825
- | `--check-baseline <file>` | Validate a local manual-run baseline JSON file (`mission-proof`) |
826
- | `--id <id>` / `--status <status>` | Identify a run added with `--add-baseline-run` (`mission-proof`) |
827
- | `--minutes-spent`, `--reruns`, `--failed-gates`, `--reviewer-approvals` | Numeric fields for `--add-baseline-run` (`mission-proof`) |
828
- | `--write <file>` | Write a Markdown or JSON artifact (`mission-proof`, `handoff`) |
829
- | `--require-passed` | Exit nonzero unless every selected mission bundle passed proof (`mission-proof`) |
830
- | `--summary` | Print one compact Mission Proof status line (`mission-proof`) |
831
- | `--task-card` | Print only the Mission Control Markdown task card (`start`) |
832
- | `--review-gate` | Print only the Mission Control stop-and-review gate (`start`) |
833
- | `--review-gate-json` | Print only the Mission Control review gate as JSON (`start`) |
834
- | `--review-policy` | Print only the Mission Control review policy as JSON (`start`) |
835
- | `--review-replies` | Print only copyable Mission Control reviewer replies (`start`) |
836
- | `--runbook` | Print only the Mission Control Markdown runbook (`start`) |
837
- | `--changed-only` | Scope to files changed vs base ref (ci/analyze/doctor) |
838
- | `--base-ref <ref>` | Git base ref for `--changed-only` (default: origin/main) |
839
- | `--report-policy <name>` | Use a named report policy preset from config (`analyze`, `doctor`, `ci`) |
840
- | `--report-scope <paths>` | Comma-separated repo-relative paths to include in exported evidence (`analyze`, `doctor`, `ci`) |
841
- | `--redact-paths` | Replace file paths in exported evidence with stable labels (`analyze`, `doctor`, `ci`) |
842
- | `--reporter <name>` | Render `doctor`, `analyze`, or `ci` with a local reporter plugin |
843
- | `--verbose` | Enable debug output |
844
- | `--quiet` | Suppress non-essential output |
845
- | `-V, --version` | Show version |
846
- | `-h, --help` | Show help |
847
-
848
- ## Health Score
849
-
850
- Every `projscan doctor` run calculates a health score (0–100) and letter grade:
851
-
852
- | Grade | Score | Meaning |
853
- | ----- | ------ | ------------------------------------------ |
854
- | A | 90–100 | Excellent - project follows best practices |
855
- | B | 80–89 | Good - minor improvements possible |
856
- | C | 70–79 | Fair - several issues to address |
857
- | D | 60–69 | Poor - significant issues found |
858
- | F | < 60 | Critical - major issues need attention |
859
-
860
- Generate a badge for your README:
163
+ Add `--watch` if the client supports `notifications/file_changed`:
861
164
 
862
165
  ```bash
863
- projscan badge
166
+ npx -y projscan mcp --watch
864
167
  ```
865
168
 
866
- This outputs a [shields.io](https://shields.io) badge URL and markdown snippet you can paste into your README.
867
-
868
- **Sample badge:** [![projscan health](https://img.shields.io/badge/projscan-D-orange)](https://github.com/abhiyoheswaran1/projscan)
869
-
870
- ## What It Detects
871
-
872
- **Languages**: 11 AST adapters covering 12 named languages: TypeScript, JavaScript, Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, and C++. projscan also provides file-level detection for C, Dart, Lua, Scala, R, Shell, CSS, HTML, SQL, and more.
873
-
874
- **Frameworks**: React, Next.js, Vue, Nuxt, Svelte, Angular, Express, Fastify, NestJS, Vite, Tailwind CSS, Prisma, and more
875
-
876
- ### Python (0.10)
877
-
878
- Python repos now get the same treatment JS/TS has had since 0.6:
879
-
880
- - **AST-accurate import graph.** `from pkg.mod import x`, relative imports, `__init__.py` packages, `__all__`. Parsed via tree-sitter-python (wasm, offline).
881
- - **Python-aware analyzers.** Missing pytest / ruff / black config. Deprecated packages (nose, simplejson, pycrypto). Unused `pyproject.toml` / `requirements.txt` deps. Missing lockfile.
882
- - **Python upgrade preview.** `projscan upgrade requests` reads `pyproject.toml` (including dependency groups), `setup.cfg`, `setup.py`, root `requirements*.txt`, Poetry/Pipfile/uv/PDM/Conda lockfiles, and pinned root requirements/constraints, then reports declared scope, current-version source, drift, and importers offline. A root Python manifest is enough evidence even before `.py` files exist.
883
- - **Code search.** BM25 and semantic modes work on `.py` files out of the box.
884
- - **Hotspots + dead code.** Same scoring as JS/TS, with `__init__.py` and pytest test-file conventions understood.
885
- - **MCP tools work unchanged.** `projscan_semantic_graph`, `projscan_search`, `projscan_doctor`, `projscan_hotspots`, etc. all accept Python projects. Agents can ask "which files import `pkg.core`?" and get an answer in milliseconds.
886
-
887
- `projscan_upgrade` supports Node and Python offline previews. Python current-version evidence comes from Poetry, Pipfile, uv, PDM, Conda lockfiles, pinned root requirements, or pinned root constraints when present. Registry lookup remains npm-only behind `--check-registry`.
888
-
889
- ### Go (0.11)
890
-
891
- Go flows through the same pipeline as JS/TS and Python:
892
-
893
- - **AST-accurate import graph** via tree-sitter-go. Single-line and parenthesized import blocks, aliased imports, dot-imports.
894
- - **Capitalization-rule export visibility** - uppercase identifiers are public, lowercase are private. Captures `func`, method, `var`, `const`, `type` (struct/interface).
895
- - **`go.mod` module-path resolution** - imports prefixed with the module path resolve into the repo; stdlib and third-party are external.
896
- - **Cyclomatic complexity** counted from `if`, `for`, `switch` cases, select communication cases, `&&`/`||`. Default cases and `defer`/`go` don't count.
169
+ ### Agent Questions
170
+
171
+ | Agent question | CLI or MCP route |
172
+ | -------------------------------------------- | -------------------------------------------------------------------------------- |
173
+ | Which files implement auth? | `projscan search "auth" --format json` |
174
+ | Who imports this file? | `projscan semantic-graph --query importers --file src/auth/jwt.ts --format json` |
175
+ | What breaks if I rename this symbol? | `projscan impact --symbol buildCodeGraph --format json` |
176
+ | What should I fix first? | `projscan bug-hunt --format json` |
177
+ | Which files have high risk and low coverage? | `projscan coverage --format json` |
178
+ | What should my agent do next? | `projscan workplan --format json` |
179
+ | Which proof belongs in this PR? | `projscan evidence-pack --pr-comment` |
180
+ | Is this branch ready to merge? | `projscan preflight --mode before_merge --format json` |
181
+
182
+ ## Command Map
183
+
184
+ | Command | Use it when you need |
185
+ | ------------------------- | -------------------------------------------------------------------------- |
186
+ | `projscan start` | first-60-seconds orientation, routing, and Mission Control |
187
+ | `projscan understand` | cited repo map, runtime flows, public contracts, and change readiness |
188
+ | `projscan preflight` | proceed, caution, or block gate for edit, commit, or merge |
189
+ | `projscan evidence-pack` | PR-ready proof with risks, owners, and next commands |
190
+ | `projscan bug-hunt` | ranked fix queue from health, hotspots, session, and preflight evidence |
191
+ | `projscan workplan` | ordered agent tasks with proof and handoff text |
192
+ | `projscan doctor` | project health, tooling gaps, dead code, and supply-chain signals |
193
+ | `projscan review` | one-call PR review from structural diff, risk, cycles, functions, and deps |
194
+ | `projscan impact` | blast radius for a file or symbol before rename, delete, or upgrade |
195
+ | `projscan semantic-graph` | imports, exports, importers, symbol definitions, and package importers |
196
+ | `projscan dataflow` | framework-aware source-to-sink risks |
197
+ | `projscan hotspots` | churn, complexity, ownership, and coverage risk ranking |
198
+ | `projscan coverage` | high-risk files with weak test coverage |
199
+ | `projscan dependencies` | dependency inventory, license summary, and risk notes |
200
+ | `projscan upgrade <pkg>` | offline upgrade impact from changelog and importer evidence |
201
+ | `projscan audit` | normalized `npm audit` findings and SARIF |
202
+ | `projscan coordinate` | collisions, claims, and merge-risk across worktrees |
203
+ | `projscan plugin` | local analyzer and reporter plugin workflow |
204
+ | `projscan privacy-check` | local scan boundary, telemetry, ignore rules, and network-capable paths |
205
+ | `projscan mcp` | MCP server over stdio |
206
+
207
+ Run the generated command help when you need flags:
897
208
 
898
- ### Coupling and cycles (0.11)
899
-
900
- `projscan coupling` (CLI + MCP tool) reports per-file fan-in / fan-out / instability (Bob Martin's I = Ce / (Ca + Ce)) and detects circular imports via Tarjan SCC. Cross-package edges are flagged when running on a monorepo.
901
-
902
- Plain-language Mission Control intents such as `projscan start --intent "show circular dependencies"` route straight to `projscan coupling --cycles-only --format json`; broader boundary questions such as `projscan start --intent "what modules are tightly coupled"` route to the full coupling report.
903
-
904
- ### PR-aware structural diff (0.11)
905
-
906
- `projscan pr-diff` returns the structural diff between two refs: exports added/removed/renamed, imports added/removed, call sites added/removed, ΔCC, Δfan-in. Spins up a temporary git worktree at the base ref to build a clean second graph. Renames are detected via similarity scoring (max of normalized Levenshtein and shared-affix fraction, threshold 0.5).
907
-
908
- ### Monorepo support (0.11)
909
-
910
- Detects npm/yarn workspaces, `pnpm-workspace.yaml`, Lerna, modern Nx (`nx.json#workspaceLayout` + `project.json` scan), legacy Nx (`workspace.json#projects`), and a `packages/*` + `apps/*` + `libs/*` fallback. `projscan workspaces` lists every package; `--package <name>` (or the `package` MCP arg) scopes most commands to a single workspace.
911
-
912
- Cache version bumped 2 → 3 in 0.11 (CC stored per file). Existing v2 caches are discarded on first run and rebuilt automatically.
913
-
914
- ## Performance
915
-
916
- Reference numbers from `npm run bench` on an Apple M3 Pro running Node 25 (cold / warm cache, milliseconds), refreshed for 1.5.0:
917
-
918
- | Repo | Files | analyze | doctor | hotspots | coupling | search |
919
- | ---------------- | ----- | --------- | --------- | --------- | --------- | --------- |
920
- | projscan itself | ~120 | 650 / 576 | 659 / 574 | 794 / 622 | 405 / 186 | 485 / 277 |
921
- | Synthetic medium | 500 | 284 / 257 | 277 / 255 | 300 / 278 | 224 / 177 | 239 / 196 |
922
-
923
- For real-world numbers against larger codebases, `npm run bench:references` shallow-clones TypeScript, Django, and kubernetes/client-go into `.bench-cache/` (gitignored) and runs the same suite. First run is network-bound; later runs reuse the cache. Restrict to one target with `-- --only ts|django|k8s-client-go`.
924
-
925
- Run `npm run bench` against your own machine to recalibrate.
926
-
927
- - **Local by default** — core scans run without network; `audit`, registry checks, opt-in telemetry, and optional semantic embeddings are explicit network-capable paths
928
- - **7 direct runtime dependencies** — grammar packages are build-time sources, not global-install dependencies
929
- - **~21 MB of vendored tree-sitter WASM grammars**, broken down:
930
-
931
- | Vendored file | Size | Languages |
932
- | -------------------------- | ------: | ---------------------------------- |
933
- | `web-tree-sitter.wasm` | ~190 KB | runtime, all tree-sitter languages |
934
- | `tree-sitter-python.wasm` | ~450 KB | Python |
935
- | `tree-sitter-go.wasm` | ~210 KB | Go |
936
- | `tree-sitter-java.wasm` | ~405 KB | Java |
937
- | `tree-sitter-ruby.wasm` | ~2.0 MB | Ruby |
938
- | `tree-sitter-rust.wasm` | ~1.1 MB | Rust |
939
- | `tree-sitter-php.wasm` | ~785 KB | PHP |
940
- | `tree-sitter-c_sharp.wasm` | ~5.2 MB | C# |
941
- | `tree-sitter-cpp.wasm` | ~3.3 MB | C, C++ |
942
- | `tree-sitter-kotlin.wasm` | ~3.9 MB | Kotlin |
943
- | `tree-sitter-swift.wasm` | ~3.6 MB | Swift |
944
-
945
- JavaScript and TypeScript use the bundled `@babel/parser` instead of a tree-sitter grammar, so they don't appear in this table.
946
-
947
- ## Optional features
948
-
949
- projscan keeps the install slim by default. One feature is gated behind an optional peer dependency:
950
-
951
- - **Semantic search** uses local embeddings via `@xenova/transformers` (~25 MB quantized model, downloads on first use, then cached). Without it, `projscan search` falls back to BM25 lexical search and prints a one-line tip pointing here. Install when you want it:
952
-
953
- ```bash
954
- npm install @xenova/transformers
955
- projscan search "cache invalidation" --semantic
956
- ```
957
-
958
- See [AI Agent Integration → Semantic search](#semantic-search-090-opt-in) for details.
959
-
960
- ## Security & trust
961
-
962
- projscan reads your source code so it can be useful; it does not send your source code anywhere. This section explains exactly what's happening, because supply-chain scanners (Socket, Snyk, npm audit, etc.) will flag a few patterns in any tool that wraps `git` and `npm`, and we want you to be able to verify our claims rather than trust them.
963
-
964
- ### What projscan does NOT do
965
-
966
- - **Send your source code off-machine.** File contents stay local; AST analysis runs in-process. The only projscan-owned network path is explicit opt-in telemetry, and those events are anonymous product-health buckets, not code or scan results.
967
- - **Read environment variables for secrets.** `process.env` is forwarded to child processes (`git`, `npm`) so they can find their `PATH` — we never inspect `.env` values, API keys, or session tokens.
968
- - **Execute command-line arguments as code.** Core CLI and MCP arguments are parsed as data, and projscan does not compose shell strings from user input. Local plugins are the explicit trust boundary: `projscan plugin test` is static by default, and projscan imports local modules declared in `.projscan-plugins/*.projscan-plugin.json` only when execution is explicitly requested with `--execute` and `PROJSCAN_PLUGINS_PREVIEW=1` is set.
969
- - **Phone home silently.** Telemetry is off by default. If you explicitly opt in with `projscan telemetry enable` or the interactive `projscan init team` prompt, projscan sends only anonymous product-health events; it never sends source code, file paths, repo names, branch names, package names, usernames, raw findings, or secrets. See [TELEMETRY.md](TELEMETRY.md).
970
- - **Modify your repo without an explicit command.** `projscan fix` is the only command that writes to source files, and only when invoked. The cache directory `.projscan-cache/` is local-only and gitignored.
971
-
972
- ### What projscan DOES do, and what it costs
973
-
974
- | Action | When | Network? | Notes |
975
- | ---------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
976
- | Read source files | every command | no | parses with tree-sitter / Babel; results cached at `.projscan-cache/` |
977
- | Spawn `git` | `hotspots`, `pr-diff`, `review`, `diff` | git itself may fetch if you run `git fetch` separately; **projscan never invokes `git fetch`** | `env: process.env` is passed so `git` can find its config |
978
- | Spawn `npm audit` | `audit` only | yes — by `npm`, not by projscan | runs against your local lockfile |
979
- | Scan supply-chain IOCs | `doctor`, `preflight`, release validation | no | checks manifests, lockfiles, hidden editor hooks, and suspicious install-time payloads against bundled indicators |
980
- | Anonymous telemetry | only after `projscan telemetry enable` or accepting the `projscan init team` prompt | yes — projscan-owned, default off | sends product-health buckets only; see [TELEMETRY.md](TELEMETRY.md) |
981
- | Load local plugins | only with `PROJSCAN_PLUGINS_PREVIEW=1` and an execution path such as `--execute`, `doctor`, `ci`, or `analyze` | no | imports local JS modules declared in `.projscan-plugins/`; only enable plugins you trust |
982
- | Load wasm grammars | first parse of a non-JS file | no | served from `dist/grammars/` inside the package; no fetch |
983
- | Build embeddings | semantic search opt-in only | yes — by `@xenova/transformers`, on first use | model cached locally after first download; remove the peer dep to remove this code path entirely |
984
-
985
- ### Patterns supply-chain scanners flag, and why they're benign here
986
-
987
- projscan's [Socket report](https://socket.dev/npm/package/projscan) currently shows four supply-chain alerts. Each alert maps to one of these code paths:
988
-
989
- - **"Network access"** — comes from `web-tree-sitter`'s internal API surface; we feed it local wasm files at `dist/grammars/`. No outbound traffic.
990
- - **"Dynamic require" / runtime import** — optional dependencies lazy-load from literal module names; opt-in local plugins load validated manifest module paths under `.projscan-plugins/`. Plugin execution is local code execution by design, gated by `PROJSCAN_PLUGINS_PREVIEW=1`.
991
- - **"Environment variable access"** — `env: process.env` is forwarded to child processes (`git`, `npm audit`). We don't read env contents.
992
- - **"URL strings"** — the strings are documentation references (`github.com`, `registry.npmjs.org`) shown in error messages and CHANGELOGs, not runtime fetch targets.
993
-
994
- ### Audit it yourself
995
-
996
- - **Source is open** at [github.com/abhiyoheswaran1/projscan](https://github.com/abhiyoheswaran1/projscan). The npm tarball matches the `dist/` produced by `npm run build` at the matching tag.
997
- - **Public API surface is locked** by `scripts/check-stability.mjs`, which runs in CI on every PR and fails on any rename or removal of an MCP tool, CLI command, or exit code. See [`docs/STABILITY.md`](https://github.com/abhiyoheswaran1/projscan/blob/v4.3.1/docs/STABILITY.md).
998
- - **Run it offline:** `npm install -g projscan` followed by anything except `audit` and `--mode semantic` works without network.
999
- - **Drop privilege further:** in CI, run projscan in a sandbox that disallows network egress; everything except `audit` will pass.
1000
-
1001
- ## Dogfooding
1002
-
1003
- projscan runs against itself in CI on every PR. The dogfood loop is the most direct evidence we can offer that the tool works on real code instead of synthetic fixtures alone.
1004
-
1005
- ```sh
1006
- # .github/workflows/ci.yml — runs after the unit tests
1007
- - run: node dist/cli/index.js ci --min-score 90
209
+ ```bash
210
+ projscan help
211
+ projscan <command> --help
1008
212
  ```
1009
213
 
1010
- Current state of the projscan codebase as scored by projscan itself:
214
+ ## Output Formats
1011
215
 
1012
- | Metric | Value |
1013
- | ----------------- | ------------------------------------------------------------------------------------------------ |
1014
- | Health score | **A (100 / 100)** |
1015
- | Open issues | 0 errors, 0 warnings, 0 info |
1016
- | Circular imports | 0 |
1017
- | Top hotspot | `src/reporters/consoleReporter.ts` (CC 288, 1108 lines) — known refactor candidate, not a defect |
1018
- | Dogfood threshold | `--min-score 90` (CI fails below this) |
216
+ Commands support `console`, `json`, `markdown`, `sarif`, and `html` where those formats fit the command.
1019
217
 
1020
- The `--min-score 90` threshold is deliberately tight: a regression that drops the score by more than ten points fails the build. The current ten-point margin (90 → 100) is for room to breathe, not slack.
1021
-
1022
- For adoption proof, run the product against multiple real repos and capture first-PR feedback:
1023
-
1024
- ```sh
218
+ ```bash
219
+ projscan analyze --format json
220
+ projscan doctor --format markdown
221
+ projscan ci --format sarif > projscan.sarif
1025
222
  projscan evidence-pack --pr-comment
1026
- projscan feedback init --output .projscan-feedback.json
1027
- projscan feedback add --file .projscan-feedback.json --repo api --pr https://github.com/acme/api/pull/42 --reviewer @alice --useful true --minutes-saved 10 --owner-routing-clear true --next-command-clear true
1028
- projscan feedback summary --file .projscan-feedback.json --format json
1029
- projscan dogfood --repo ../api --repo ../web --repo ../worker --feedback .projscan-feedback.json --format json
1030
- projscan trial --repo ../api --repo ../web --repo ../worker --feedback .projscan-feedback.json --format json
223
+ projscan mission-proof --write reports/mission-proof.md
1031
224
  ```
1032
225
 
1033
- The dogfood and trial reports check PR-comment readiness, repeat-use commands, MCP readiness, measured minutes saved, prevented bad edits, false positives, owner clarity, next-command clarity, and repeat PR usage before rollout.
1034
-
1035
- The hotspots projscan finds in itself are real signals — the reporters in particular have grown organically across releases and remain future refactor candidates in the roadmap. We choose to ship the signal honestly rather than tune the score to hide it.
1036
-
1037
- ## CI/CD Integration
1038
-
1039
- Use `projscan ci` to gate your pipelines:
226
+ Use scoped and redacted reports when evidence leaves the repo:
1040
227
 
1041
228
  ```bash
1042
- projscan ci --min-score 70 # Exits 1 if score < 70
1043
- projscan ci --min-score 80 --format json # JSON output for parsing
1044
- projscan ci --changed-only # Gate only on this PR's diff
1045
- projscan ci --format sarif > projscan.sarif # SARIF for Code Scanning
229
+ projscan analyze --report-scope src/api --redact-paths --format json
230
+ projscan analyze --report-scope "src/api,packages/backend" --redact-paths --format json
231
+ projscan doctor --report-policy apiEvidence --format markdown
1046
232
  ```
1047
233
 
1048
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/npx%20projscan%20ci%20--min-score%2070.gif" alt="npx projscan ci --min-score 70" width="700">
1049
-
1050
- ### GitHub Action (recommended)
1051
-
1052
- projscan ships a first-party GitHub Action that installs, runs, and uploads SARIF to **GitHub Code Scanning** in one step:
1053
-
1054
- ```yaml
1055
- # .github/workflows/projscan.yml
1056
- name: ProjScan
1057
- on:
1058
- push: { branches: [main] }
1059
- pull_request: { branches: [main] }
1060
-
1061
- permissions:
1062
- contents: read
1063
- security-events: write # required for SARIF upload
1064
-
1065
- jobs:
1066
- scan:
1067
- runs-on: ubuntu-latest
1068
- steps:
1069
- - uses: actions/checkout@v4
1070
- with: { fetch-depth: 0 } # needed for --changed-only
1071
- - uses: actions/setup-node@v4
1072
- with: { node-version: 20 }
1073
- - uses: abhiyoheswaran1/projscan@v1
1074
- with:
1075
- min-score: '70'
1076
- changed-only: 'true'
1077
- ```
234
+ ## Configuration
1078
235
 
1079
- Inputs: `min-score`, `changed-only`, `base-ref`, `config`, `sarif-file`, `upload-sarif`, `working-directory`, `version`. Outputs: `score`, `grade`.
1080
-
1081
- Findings appear in the **Security → Code scanning** tab, annotated on files and lines. PRs get inline annotations on changed lines.
1082
-
1083
- ### Plain workflow (no SARIF upload)
1084
-
1085
- If you'd rather not upload SARIF, [`.github/projscan-ci.yml`](.github/projscan-ci.yml) is a drop-in workflow that runs projscan and posts a markdown health report as a PR comment.
1086
-
1087
- ## Configuration (`.projscanrc`)
1088
-
1089
- Drop a `.projscanrc.json` at your repo root to set defaults - CLI flags always win over config. A `"projscan"` key in `package.json` and plain `.projscanrc` are also supported.
236
+ Create a `.projscanrc.json` when repo defaults should live in source control:
1090
237
 
1091
238
  ```json
1092
239
  {
@@ -1098,7 +245,7 @@ Drop a `.projscanrc.json` at your repo root to set defaults - CLI flags always w
1098
245
  "scanEnvValues": false,
1099
246
  "offline": false
1100
247
  },
1101
- "disableRules": ["missing-editorconfig", "large-*"],
248
+ "disableRules": ["large-*"],
1102
249
  "severityOverrides": {
1103
250
  "missing-prettier": "info"
1104
251
  },
@@ -1107,426 +254,135 @@ Drop a `.projscanrc.json` at your repo root to set defaults - CLI flags always w
1107
254
  "reportScope": ["src/api", "packages/backend"],
1108
255
  "redactPaths": true
1109
256
  }
1110
- },
1111
- "hotspots": {
1112
- "limit": 20,
1113
- "since": "6 months ago"
1114
257
  }
1115
258
  }
1116
259
  ```
1117
260
 
1118
- Fields:
1119
-
1120
- - `minScore` - default `ci` threshold (0–100)
1121
- - `baseRef` - default base ref for `--changed-only`
1122
- - `ignore` - extra glob patterns added to the built-in ignore list
1123
- - `scan.includeIgnored` - opt into scanning files hidden by Git ignore rules
1124
- - `scan.scanEnvValues` - opt into reading `.env*` contents during secret checks
1125
- - `scan.offline` - block projscan network-capable features by default
1126
- - `disableRules` - silence rules by id; supports wildcard `prefix-*`
1127
- - `severityOverrides` - remap a rule's severity (`info` / `warning` / `error`)
1128
- - `reportPolicies.<name>` - reusable evidence export preset for `analyze`, `doctor`, and `ci`
1129
- - `hotspots.limit` / `hotspots.since` - defaults for the `hotspots` command
1130
- - `monorepo.importPolicy` - cross-package import allow/deny rules in monorepos _(0.14+)_
1131
-
1132
- See [`docs/GUIDE.md` -> Configuration](https://github.com/abhiyoheswaran1/projscan/blob/v4.3.1/docs/GUIDE.md#configuration-projscanrc) for the full reference (field types, validation behavior, embedding config in `package.json`, monorepo `importPolicy` semantics).
1133
-
1134
- ## Tracking Health Over Time
1135
-
1136
- Save a baseline and compare later:
1137
-
1138
- ```bash
1139
- projscan diff --save-baseline # Save current score
1140
- # ... make changes ...
1141
- projscan diff # Compare against baseline
1142
- projscan diff --format markdown # Markdown diff for PRs
1143
- ```
1144
-
1145
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/npx%20projscan%20diff%20--save-baseline.gif" alt="npx projscan diff --save-baseline" width="700">
1146
-
1147
- ## Hotspots - Where to Fix First
1148
-
1149
- A flat health score doesn't tell you what to do. **`projscan hotspots`** combines `git log` churn, file complexity, open issues, recency, and **ownership** into a single risk score per file, so you know where refactoring or review will pay off.
1150
-
1151
- <img src="https://abhiyoheswaran.com/images/projscan/hotspots-poster.png" alt="projscan hotspots output ranking files by composite risk score" width="700">
1152
-
1153
- ```bash
1154
- projscan hotspots # Top 10 hotspots
1155
- projscan hotspots --limit 20
1156
- projscan hotspots --since "6 months ago"
1157
- projscan hotspots --format json # Machine-readable for dashboards
1158
- projscan hotspots --format markdown # Drop into a PR or tech-debt ticket
1159
- ```
261
+ Config docs live in [docs/GUIDE.md](docs/GUIDE.md#configuration-projscanrc).
1160
262
 
1161
- Hotspot ranking follows the classic Feathers "churn × complexity" heuristic with boosts for files that fail `projscan doctor`, changed recently, or show **bus factor 1** (single-author + high churn). Falls back gracefully outside a git repo.
263
+ ## CI
1162
264
 
1163
- ### Drill Into a Hotspot
265
+ Use `projscan ci` to gate pull requests:
1164
266
 
1165
267
  ```bash
1166
- projscan file src/cli/index.ts
268
+ projscan ci --min-score 80
269
+ projscan ci --changed-only
270
+ projscan ci --format sarif > projscan.sarif
1167
271
  ```
1168
272
 
1169
- Combines the file's purpose, imports, exports, hotspot risk, ownership, and every open issue that references it - the natural follow-up to `projscan hotspots`.
273
+ GitHub Actions example:
1170
274
 
1171
- ### Track Trends Over Time
1172
-
1173
- ```bash
1174
- projscan diff --save-baseline # Snapshots health + hotspots
1175
- # ...time passes, commits happen...
1176
- projscan diff # Shows which hotspots rose / fell
1177
- ```
1178
-
1179
- The baseline file now captures top hotspots too, so `diff` surfaces files that are **getting worse** alongside new issues.
1180
-
1181
- ## Dependency Health
1182
-
1183
- projscan ships focused commands for checking your dependency graph. Drift and upgrade previews run **offline** by default; `audit` wraps `npm audit` and can contact the npm registry.
1184
-
1185
- ```bash
1186
- projscan outdated # Which declared deps drift from what's installed?
1187
- projscan outdated --format json # Machine-readable drift report
1188
- projscan audit # Wrap npm audit; normalized, SARIF-ready
1189
- projscan audit --format sarif > a.sarif # Upload to GitHub Code Scanning
1190
- projscan upgrade chalk # What breaks if I bump chalk? Who imports it?
1191
- projscan upgrade chalk --format markdown # Paste-ready review comment
1192
- ```
1193
-
1194
- ### What each one tells you
1195
-
1196
- - **`outdated`** - reads `package.json` and `node_modules/<pkg>/package.json` to classify drift (`major` / `minor` / `patch` / `same` / `unknown`). No network.
1197
- - **`audit`** - wraps `npm audit --json`, normalizes the output, and emits SARIF with per-finding rules anchored to `package.json`. Graceful fallback message for yarn/pnpm projects.
1198
- - **`upgrade <pkg>`** - reads `node_modules/<pkg>/CHANGELOG.md` for npm packages or Python manifests/lockfiles for Python packages, flags available breaking-change markers, and lists every file in your repo that imports the package. All offline unless `--check-registry` is passed for npm.
1199
-
1200
- ### Unused dependencies (automatic in `doctor`)
1201
-
1202
- `projscan doctor` now flags declared dependencies that are never imported from source. Each finding is anchored to the **exact line in `package.json`** so GitHub Code Scanning PR annotations land in the right place.
1203
-
1204
- Implicit-use packages (typescript, eslint/prettier plugins, `@types/*`, and anything invoked from a `package.json` script) are allowlisted. Override via `.projscanrc` → `disableRules` if projscan flags something that is used but not imported.
1205
-
1206
- ## Coverage × Hotspots - Scariest Untested Files
275
+ ```yaml
276
+ name: ProjScan
277
+ on:
278
+ pull_request:
279
+ branches: [main]
1207
280
 
1208
- `projscan coverage` joins your test coverage with the hotspot ranking. A file with high churn and low coverage is where a bug is most likely to bite you - so that's where you want tests first.
281
+ permissions:
282
+ contents: read
283
+ security-events: write
1209
284
 
1210
- ```bash
1211
- projscan coverage # Top 30 scariest untested files
1212
- projscan coverage --format markdown # Paste into a tech-debt ticket
1213
- projscan coverage --format json # Machine-readable for dashboards
285
+ jobs:
286
+ scan:
287
+ runs-on: ubuntu-latest
288
+ steps:
289
+ - uses: actions/checkout@v4
290
+ with: { fetch-depth: 0 }
291
+ - uses: actions/setup-node@v4
292
+ with: { node-version: 24 }
293
+ - uses: abhiyoheswaran1/projscan@v1
294
+ with:
295
+ min-score: '80'
296
+ changed-only: 'true'
1214
297
  ```
1215
298
 
1216
- **How it decides "scariest":** `priority = riskScore × (0.3 + 0.7 × uncoveredFraction)` - so a file with 50 risk and 10% coverage outranks a file with 50 risk and 95% coverage.
299
+ ## Plugins
1217
300
 
1218
- **Which coverage files are supported:**
301
+ Local plugins let teams add project-specific analyzer rules and custom human reports without changing projscan core.
1219
302
 
1220
- - `coverage/lcov.info` (lcov - Vitest, Jest, c8)
1221
- - `coverage/coverage-final.json` (Istanbul per-file detail)
1222
- - `coverage/coverage-summary.json` (Istanbul summary)
1223
-
1224
- Coverage is also automatically joined into `projscan hotspots` when one of those files exists - no flag needed. Uncovered churning files get a score bump and a `low coverage (X%)` reason tag.
1225
-
1226
- ### Dead-code detection (automatic in `doctor`)
1227
-
1228
- `projscan doctor` now flags source files whose exports nothing imports - dead code left over from refactors or utilities that were never wired up. Respects `package.json` public entry points (`main`, `exports`, `bin`, `types`), skips test files and barrel (`index`) files.
1229
-
1230
- ## AI Agent Integration (MCP)
1231
-
1232
- Use MCP when an AI coding agent should call projscan directly. `projscan mcp` starts an [MCP](https://modelcontextprotocol.io) server over stdio and exposes the same local proof behind the daily workflows: repo context, impact, hotspots, review gates, and next commands.
1233
-
1234
- <img src="https://raw.githubusercontent.com/abhiyoheswaran1/projscan/v4.3.1/docs/projscan-agent-demo.gif" alt="projscan answering two agent questions: what breaks if I rename buildCodeGraph (impact analysis with definitions, direct callers, transitive reach), and where should I fix first (ranked hotspots with cyclomatic complexity)" width="700">
1235
-
1236
- Two common agent questions: _"What breaks if I rename `buildCodeGraph`?"_ → 31 direct callers, 97 files reachable. _"Where should I fix first?"_ → ranked hotspots with AST cyclomatic complexity, churn, and ownership signals.
1237
-
1238
- ### Claude Code
1239
-
1240
- One-liner — adds projscan as an MCP server in the current project:
303
+ ### Load local plugins
1241
304
 
1242
305
  ```bash
1243
- claude mcp add projscan -- npx -y projscan mcp
1244
- ```
1245
-
1246
- ### Codex CLI (OpenAI)
1247
-
1248
- Add to `~/.codex/config.toml`:
1249
-
1250
- ```toml
1251
- [mcp_servers.projscan]
1252
- command = "npx"
1253
- args = ["-y", "projscan", "mcp"]
1254
- ```
1255
-
1256
- Restart `codex` and the tool surface (`projscan_semantic_graph`, `projscan_review`, …) appears alongside Codex's built-ins.
1257
-
1258
- ### Gemini CLI (Google)
1259
-
1260
- Add to `~/.gemini/settings.json`:
1261
-
1262
- ```json
1263
- {
1264
- "mcpServers": {
1265
- "projscan": {
1266
- "command": "npx",
1267
- "args": ["-y", "projscan", "mcp"]
1268
- }
1269
- }
1270
- }
1271
- ```
1272
-
1273
- ### Cursor
1274
-
1275
- Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):
1276
-
1277
- ```json
1278
- {
1279
- "mcpServers": {
1280
- "projscan": {
1281
- "command": "npx",
1282
- "args": ["-y", "projscan", "mcp"]
1283
- }
1284
- }
1285
- }
1286
- ```
1287
-
1288
- ### Windsurf
1289
-
1290
- Add to `~/.codeium/windsurf/mcp_config.json`:
1291
-
1292
- ```json
1293
- {
1294
- "mcpServers": {
1295
- "projscan": {
1296
- "command": "npx",
1297
- "args": ["-y", "projscan", "mcp"]
1298
- }
1299
- }
1300
- }
1301
- ```
1302
-
1303
- ### Cline (VS Code extension)
1304
-
1305
- In Cline's MCP settings panel (or the underlying `cline_mcp_settings.json`):
1306
-
1307
- ```json
1308
- {
1309
- "mcpServers": {
1310
- "projscan": {
1311
- "command": "npx",
1312
- "args": ["-y", "projscan", "mcp"]
1313
- }
1314
- }
1315
- }
306
+ projscan plugin list
307
+ projscan plugin validate .projscan-plugins/team-radar.projscan-plugin.json
308
+ projscan plugin test .projscan-plugins/team-radar.projscan-plugin.json
309
+ PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --reporter team-radar
1316
310
  ```
1317
311
 
1318
- ### Continue.dev
1319
-
1320
- Add to `~/.continue/config.yaml`:
1321
-
1322
- ```yaml
1323
- mcpServers:
1324
- - name: projscan
1325
- command: npx
1326
- args:
1327
- - -y
1328
- - projscan
1329
- - mcp
1330
- ```
312
+ Run `projscan help` for the generated command-by-command support matrix.
1331
313
 
1332
- ### Zed
314
+ <img src="docs/projscan-reporter-plugin.png" alt="projscan reporter plugin rendering a team health report" width="760">
1333
315
 
1334
- Add to `~/.config/zed/settings.json` under `context_servers`:
316
+ Plugin docs:
1335
317
 
1336
- ```json
1337
- {
1338
- "context_servers": {
1339
- "projscan": {
1340
- "command": {
1341
- "path": "npx",
1342
- "args": ["-y", "projscan", "mcp"]
1343
- }
1344
- }
1345
- }
1346
- }
1347
- ```
318
+ - [Plugin Authoring](docs/PLUGIN-AUTHORING.md)
319
+ - [Plugin Gallery](docs/PLUGIN-GALLERY.md)
320
+ - [2.0 Migration Guide](docs/2.0-MIGRATION.md)
321
+ - [Manifest Schema](docs/plugin.schema.json)
1348
322
 
1349
- ### Any other MCP-aware client
323
+ ## Supported Repos
1350
324
 
1351
- The transport is **stdio**. Wire your client to invoke `npx -y projscan mcp` as a subprocess; the server speaks JSON-RPC 2.0 over stdin/stdout. If your client wants `notifications/file_changed` push notifications when the repo changes, append `--watch`:
325
+ projscan reads TypeScript, JavaScript, Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, C, and C++ with AST-aware adapters where available. It also detects file-level signals for Shell, CSS, HTML, SQL, Dart, Lua, Scala, R, and related project files.
1352
326
 
1353
- ```bash
1354
- npx -y projscan mcp --watch
1355
- ```
327
+ Framework signals cover React, Next.js, Vue, Nuxt, Svelte, Angular, Express, Fastify, NestJS, Vite, Tailwind CSS, Prisma, Remix, SvelteKit, Astro, Hono, Koa, and common monorepo layouts.
1356
328
 
1357
- Capability is advertised under `experimental.fileChanged` on `initialize` so clients can detect support.
1358
-
1359
- ### What agents can ask
1360
-
1361
- - _"Who imports `src/auth/jwt.ts`?"_ → `projscan_semantic_graph { query: { direction: "importers", file: "src/auth/jwt.ts" } }` or `projscan semantic-graph --query importers --file src/auth/jwt.ts --format json`
1362
- - _"Which files import `chalk`?"_ or _"Which files import package `chalk`?"_ → `projscan_semantic_graph { query: { direction: "package_importers", symbol: "chalk" } }` or `projscan semantic-graph --query package_importers --symbol chalk --format json`
1363
- - _"Give me the whole agent-safe graph contract."_ → `projscan_semantic_graph`
1364
- - _"Did this wrapper connect a source reader to a dangerous sink?"_ → `projscan_dataflow`
1365
- - _"Explain issue `missing-test-framework`."_ → `projscan_explain_issue { issue_id: "missing-test-framework" }`
1366
- - _"Where is `runAudit` defined?"_ → `projscan_semantic_graph { query: { direction: "symbol_defs", symbol: "runAudit" } }` or `projscan semantic-graph --query symbol_defs --symbol runAudit --format json`
1367
- - _"Which files implement auth?"_ → `projscan_search { query: "auth", scope: "content" }`
1368
- - _"Who should I ask about auth?"_ → `projscan_search { query: "auth" }`
1369
- - _"Which tests cover auth?"_ → `projscan_search { query: "tests for auth" }`
1370
- - _"What are the scariest untested files?"_ → `projscan_coverage`
1371
- - _"Which files have no tests?"_ → `projscan_coverage`
1372
- - _"What breaks if I bump chalk to 6?"_ → `projscan_upgrade { package: "chalk" }`
1373
- - _"Show circular dependencies."_ → `projscan_coupling { direction: "cycles_only" }` or `projscan coupling --cycles-only --format json`
1374
- - _"What modules are tightly coupled?"_ → `projscan_coupling` or `projscan coupling --format json`
1375
- - _"Where should I refactor first?"_ → `projscan_hotspots`
1376
- - _"What should my agent do first in this repo?"_ → `projscan_start { mode: "before_edit" }`
1377
- - _"How do I understand the repo before editing?"_ → `projscan_understand { view: "map" }`
1378
- - _"What should my agent do next?"_ → `projscan_workplan { mode: "bug_hunt" }`
1379
- - _"Give the next agent a compact brief."_ → `projscan_agent_brief { intent: "bug_hunt" }`
1380
- - _"Show the product quality picture."_ → `projscan_quality_scorecard`
1381
- - _"What should I fix before a big release?"_ → `projscan_bug_hunt`
1382
- - _"What evidence do I need before approval?"_ → `projscan_evidence_pack { website_prompt: true }`
1383
- - _"Which checks prove this bigger product update?"_ → `projscan_regression_plan { level: "full" }`
1384
- - _"How do I plan the next six product lines?"_ → `projscan_release_train`
1385
- - _"How do I wire projscan into this MCP client?"_ → `projscan_adoption { action: "mcp_config", client: "codex" }`
1386
-
1387
- ### The 45 MCP tools
1388
-
1389
- **Structural (0.6.0 / 0.11 / 0.13 / 0.14 / 0.15 - agent-native):**
1390
-
1391
- - **`projscan_start`** _(3.0.4)_ - first-60-seconds repo orientation. Composes setup diagnostics, `firstTenMinutes`, workflow recipes, workplan, quality scorecard, top risks, adoption gaps, next commands, and optional handoff payload.
1392
- - **`projscan_understand`** _(3.4)_ - cited repo-comprehension report with `map`, `flow`, `contracts`, `change`, and `verify` views, read-first files, unknowns, change readiness, verification tiers, and exact next commands.
1393
- - **`projscan_semantic_graph`** _(3.0; query mode 4.0)_ - the code graph, two ways. With no `query`: the stable v3 semantic graph contract (file, function, package, and symbol nodes plus `defines`, `imports`, `imports_package`, `exports`, and `calls` edges). With `query: { direction, file?, symbol? }`: one cheap targeted lookup — `imports`, `exports`, `importers`, `symbol_defs`, `package_importers` — with millisecond responses on a warm cache. (Subsumes the former `projscan_graph`, removed in 4.0.)
1394
- - **`projscan_dataflow`** _(3.0)_ - focused direct, propagated, and bridge source-to-sink dataflow risks. Next.js route body readers and URL reads plus Remix, SvelteKit, Astro, Hono, Express, Fastify, and Koa request sources are framework-aware, DB/write sinks are receiver-sensitive, and defaults suppress test-file paths, broad readFile/writeFile noise, JavaScript RegExp.exec false positives, and generated-code anxiety; opt into broader scans with `include_tests` / `include_broad_file_io` / `include_generated` or the matching CLI flags.
1395
- - **`projscan_search`** - fast search across `symbols` (exported names), `files` (path substring), or `content` (source substring with line + excerpt). Sub-file mode (`sub_file: true`) embeds per-function for sharper semantic results _(0.15)_.
1396
- - **`projscan_coupling`** _(0.11)_ - per-file fan-in / fan-out / instability + circular-import cycles (Tarjan SCC). Filter by `direction: cycles_only | high_fan_in | high_fan_out`.
1397
- - **`projscan_pr_diff`** _(0.11)_ - structural diff between two git refs. Returns added/removed/modified files with explicit lists of exports, imports, and call sites that changed, plus ΔCC and Δfan-in.
1398
- - **`projscan_review`** _(0.13)_ - one-call PR review. Composes `pr_diff` + per-changed-file risk + new/expanded import cycles + risky function additions + dependency changes + a verdict (`ok` / `review` / `block`).
1399
- - **`projscan_workplan`** _(2.3)_ - agent mission-control plan. Composes preflight, review, session, hotspot, plugin, and supply-chain evidence into prioritized tasks with verification commands and handoff text.
1400
- - **`projscan_bug_hunt`** _(2.3)_ - ranked bug-hunt action queue. Composes doctor issues, preflight, hotspots, and session coordination into ranked actions with verification commands.
1401
- - **`projscan_release_train`** _(2.3)_ - product-line readiness planner. Reads version, scope, readiness evidence, and next actions.
1402
- - **`projscan_evidence_pack`** _(2.3)_ - approval packet. Composes planning, bug-hunt, workplan, preflight, changelog, optional website prompt evidence, and PR comments with trust calibration, First Fix, owner routing, baseline trend memory, and exact next commands.
1403
- - **`projscan_regression_plan`** _(2.3)_ - smoke/focused/full regression matrix. Turns bug-hunt, preflight, and product risk into deduplicated verification commands.
1404
- - **`projscan_agent_brief`** _(2.3)_ - compact next-agent context packet with focus items, repo context, coordination hints, guardrails, and suggested next actions.
1405
- - **`projscan_quality_scorecard`** _(2.3)_ - dimensioned quality view across health, security, tests, maintainability, coordination, top risks, and verification commands.
1406
- - **`projscan_adoption`** _(2.9)_ - adoption helper for MCP config snippets, workflow recipes, and first-run diagnostics with the shared `firstTenMinutes` path.
1407
- - **`projscan_fix_suggest`** _(0.14)_ - structured action prompt for any open issue: headline, why it matters, where, one-paragraph instruction, optional suggested test. Closes the diagnose → fix loop.
1408
- - **`projscan_explain_issue`** _(0.14)_ - focused context for one issue: code excerpt, related issues in the same file, similar past commits via `git log --grep`, plus the structured FixSuggestion.
1409
- - **`projscan_impact`** _(0.15)_ - transitive blast-radius for a file or symbol. BFS over reverse imports + symbol callsites. Use BEFORE renaming or deleting to see what breaks.
1410
- - **`projscan_collision`** _(3.6)_ - detect change collisions across the repo's in-flight git worktrees (parallel agents). Flags same-file edits and dependency overlaps (one worktree edits a file another's change imports) before the branches merge. Local-first; needs ≥2 worktrees.
1411
- - **`projscan_claim`** _(3.6)_ - advisory claims/leases over files, directories, or symbols, shared across the repo's worktrees. `add` returns contention when another agent already holds an overlapping target; `list` / `release` manage them. Local-first.
1412
- - **`projscan_merge_risk`** _(3.6)_ - merge-risk preflight across in-flight worktrees: a safe integration order (merge the least-entangled branch first) plus conflict hotspots (files changed by 2+ worktrees). Builds on `projscan_collision`. Local-first.
1413
- - **`projscan_route`** _(3.6)_ - map a stated goal (e.g. "what breaks if I rename X") to the right projscan tool with the exact call, or list the full capability catalog. A discovery entry point over the tool surface; deterministic, no LLM.
1414
- - **`projscan_coordinate`** _(3.6)_ - one-call swarm coordination read: composes collisions, claims, and merge-risk into a `readiness` verdict (clear / caution / conflicted) with counts and the recommended integration order. The single entry point for the coordination arc. Local-first.
1415
- - **`projscan_coordinate_watch`** _(3.7)_ - long-running coordination watch: polls the in-flight worktrees and emits a `notifications/projscan/coordination_changed` notification whenever the swarm state changes. Pairs with `projscan_coordinate`. `start` / `stop` / `list`.
1416
-
1417
- **Analysis:**
1418
-
1419
- - `projscan_analyze` - full project report
1420
- - `projscan_doctor` - health score + issues (now includes `cycle-detected-N` for circular imports as of 0.13)
1421
- - `projscan_hotspots` - risk-ranked files (churn × **AST cyclomatic complexity** × issues × ownership × coverage; falls back to LOC for non-AST languages). Pass `view: "functions"` _(0.13)_ for top-N risky individual functions.
1422
- - `projscan_file` - per-file purpose, imports, exports, smells + risk + ownership + related issues + CC + fan-in/fan-out + per-function CC table _(0.13)_
1423
- - `projscan_structure` - directory tree
1424
- - `projscan_coverage` - scariest untested files (coverage × hotspots)
1425
-
1426
- **Dependencies:**
1427
-
1428
- - `projscan_dependencies` - declared deps, risks. In a monorepo: aggregated totals + `byWorkspace` breakdown; `package` arg scopes to one _(0.13)_.
1429
- - `projscan_outdated` - declared-vs-installed drift (offline). Per-package `byWorkspace`; `package` arg.
1430
- - `projscan_audit` - normalized `npm audit`. `package` arg scopes findings to one workspace's direct deps _(0.13)_.
1431
- - `projscan_upgrade` - upgrade preview (CHANGELOG + importers, offline)
1432
-
1433
- **Workspace (0.11):**
1434
-
1435
- - `projscan_workspaces` - list monorepo packages (npm/yarn/pnpm/Nx/Turbo/Lerna). Use the `name` as the `package` arg on `projscan_hotspots` / `projscan_coupling` to scope.
1436
-
1437
- **Session (1.4):**
1438
-
1439
- - **`projscan_session`** _(1.4)_ - durable cross-invocation session. Subactions: `current` (id + counts), `touched` (files touched this session, sorted by recency, filterable by source: `tool-result` / `fs-watch` / `explicit`), `events` (chronological log), `reset` (start a fresh session). Auto-populated from every tool result and from `notifications/file_changed` push events when `--watch` is on. MCP resources and agent briefs add `coordinationHints` so agents can separate current worktree checks from remembered session context before parallel edits continue.
1440
-
1441
- **Memory (1.5):**
1442
-
1443
- - **`projscan_memory`** _(1.5)_ - durable, local-only feedback loop. Records, per analyzer rule id, how many runs surfaced it and how many fixed it. Subactions: `current` (aggregate counts), `stable` (rules surfaced across ≥ 3 runs over ≥ 7 days without ever being fixed — paired with a ready-to-paste `.projscanrc.json disableRules` snippet), `runs` (every tracked rule with full history), `forget` (drop a single rule). Stored at `.projscan-memory/memory.json`; never leaves the machine. Lets an agent ask "what is this project tolerating?" and propose quieting it.
1444
-
1445
- **Operator (1.6):**
1446
-
1447
- - **`projscan_workspace_graph`** _(1.6)_ - cross-repo intelligence over locally trusted sibling repos registered with `projscan workspace add` and stored under `.projscan-cache/workspace.json`. Subactions: `list` (registered repos + parsed-file + export counts), `graph` (every symbol exported by ≥ 2 repos — the candidate refactor / API contract surface), `file_importers` (given a file in one repo, every other repo whose graph imports it). Read-only.
1448
- - **`projscan_apply_fix`** _(1.6)_ - mechanically execute the safe fix templates. Default is dry-run; pass `confirm: true` to write. Atomic writes, per-apply rollback record at `.projscan-cache/rollbacks/<id>.json`. Reverse with `action: "rollback", rollback_id: ...`. Six templates supported at this release: `unused-dependency-*`, `missing-test-framework`, `missing-eslint`, `missing-prettier`, `missing-editorconfig`, `missing-readme`.
1449
- - **`projscan_taint`** _(1.6)_ - source-to-sink reachability over the per-function call graph. Built-in defaults cover common JS / Python sources (`process.env`, `req.body`, etc.) and sinks (`exec`, `eval`, `db.query`, etc.). Project-specific names go in `.projscanrc.json` `taint`. `projscan_review` automatically diffs taint flows between base and head and **blocks any PR that introduces a new flow**. In 3.0.2, review surfaces hardened `newDataflowRisks`, compact `graphEvidence`, and graph-readiness gates for safer handoff.
1450
-
1451
- Analyzer plugins can optionally read graph/dataflow context through `check(rootPath, files, context)` while staying on manifest schema v1. The packaged `graph-context` example shows `context.getSemanticGraph()` and `context.getDataflow()` in a real analyzer. For analyzer and reporter plugin authoring, manifest validation, `--reporter <name>`, and the trust model, see [Plugin Authoring](https://github.com/abhiyoheswaran1/projscan/blob/v4.3.1/docs/PLUGIN-AUTHORING.md).
1452
-
1453
- ### Context-window budgeting
1454
-
1455
- **Every MCP tool accepts an optional `max_tokens` argument.** Set it and projscan serializes the result, and - if over budget - truncates the largest array field record-by-record until it fits. Responses include a `_budget` sidecar when truncated so your agent knows it got a partial view.
329
+ JavaScript and TypeScript use `@babel/parser`. Non-JS languages use packaged tree-sitter WASM grammars. The published package has 7 direct runtime dependencies; optional semantic search uses the peer dependency `@xenova/transformers`.
1456
330
 
1457
- ```json
1458
- { "name": "projscan_hotspots", "arguments": { "limit": 100, "max_tokens": 800 } }
1459
- ```
331
+ ## Trust Model
1460
332
 
1461
- ### Semantic search (0.9.0+, opt-in)
333
+ | Area | projscan behavior |
334
+ | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------- |
335
+ | Source code | Core scans read local files and keep results on your machine. |
336
+ | `.gitignore` | Ignored files stay out of scans unless you pass `--include-ignored`. |
337
+ | `.env` | projscan reports paths by default. It reads values after `--scan-env-values`. |
338
+ | Network | `audit`, registry checks, opt-in telemetry, and optional semantic model download can contact the network. |
339
+ | Telemetry | Off until you run `projscan telemetry enable` or accept the `init team` prompt. |
340
+ | Plugins | Local plugin code runs after `PROJSCAN_PLUGINS_PREVIEW=1` and an execution path such as `doctor`, `ci`, `analyze`, or `plugin test --execute`. |
341
+ | Repo writes | Source writes require explicit fix commands. Cache and mission proof files stay under local projscan directories. |
1462
342
 
1463
- projscan ships with BM25-ranked lexical search by default. To unlock **true semantic search** - embeddings over file content so queries like _"which file implements auth"_ hit files that don't literally contain the word "auth" - install the optional peer:
343
+ Audit helpers:
1464
344
 
1465
345
  ```bash
1466
- npm install @xenova/transformers
1467
- projscan search "verifying user credentials" --mode semantic
1468
- ```
1469
-
1470
- Or via the MCP tool:
1471
-
1472
- ```json
1473
- {
1474
- "name": "projscan_search",
1475
- "arguments": { "query": "verifying user credentials", "mode": "semantic" }
1476
- }
346
+ projscan privacy-check
347
+ projscan telemetry status
348
+ projscan telemetry explain
349
+ projscan doctor --offline
1477
350
  ```
1478
351
 
1479
- Modes on `projscan_search`:
1480
-
1481
- - `lexical` (default) - BM25 over content + symbol + path boosts. No peer needed.
1482
- - `semantic` - cosine similarity on `Xenova/all-MiniLM-L6-v2` embeddings. Requires peer.
1483
- - `hybrid` - both, fused via Reciprocal Rank Fusion. Requires peer.
1484
-
1485
- Semantic embeddings are cached at `.projscan-cache/embeddings.bin` keyed by `(model, mtime, content hash)` - invalidates automatically on file change. All offline after the first-run model download (~25MB).
1486
-
1487
- ### Pagination, progress, and streaming (0.8.0+)
352
+ Supply-chain scanners may flag package strings or APIs used by `git`, `npm audit`, `web-tree-sitter`, optional plugins, and optional semantic search. The runtime paths above describe when those capabilities run.
1488
353
 
1489
- Large responses can be walked incrementally:
354
+ ## Install Notes
1490
355
 
1491
- - **Cursor pagination**: pass `cursor` and `page_size`, get `nextCursor` back. Works on `projscan_hotspots`, `projscan_search`, `projscan_audit`, `projscan_outdated`, `projscan_coverage`.
1492
- - **Progress notifications**: set `_meta.progressToken` on the tool-call request. The server emits `notifications/progress` at coarse milestones (scanning → analyzing → ranking → done) so your agent can display progress or cancel.
1493
- - **Response chunking**: set `stream: true` in arguments to split large arrays into multiple `content` blocks (header + N chunks of ~20 records each).
356
+ `projscan@4.9.3` has seven direct runtime dependencies:
1494
357
 
1495
- All opt-in - default behavior is unchanged.
358
+ - `@babel/parser`
359
+ - `@babel/types`
360
+ - `chalk`
361
+ - `commander`
362
+ - `fast-glob`
363
+ - `ora`
364
+ - `web-tree-sitter`
1496
365
 
1497
- ### Incremental index cache
366
+ If npm prints `allow-scripts` warnings during a global install, check which package names it lists. projscan core does not need `node-gyp` grammar builds at runtime in 4.9.3. Open an issue with the warning text if npm reports install scripts from `projscan@latest`.
1498
367
 
1499
- projscan caches parsed ASTs at `.projscan-cache/graph.json` (auto-gitignored). First run populates it; subsequent runs re-parse only files whose `mtime` changed. Agent queries on a warm cache are milliseconds, not seconds.
368
+ The grammar packages are build-time sources, not global-install dependencies. Published grammar assets include `tree-sitter-python.wasm` and `tree-sitter-c_sharp.wasm`.
1500
369
 
1501
- ### Prompts (6, parameterized with live project data)
370
+ ## Deeper Docs
1502
371
 
1503
- - `prioritize_refactoring` - ranked plan grounded in current hotspots
1504
- - `investigate_file` - senior-engineer brief for a specific file
1505
- - **`refactor_hotspot`** _(1.5)_ - step-by-step refactor plan for one hotspot file
1506
- - **`triage_doctor_issues`** _(1.5)_ - critical / important / backlog ordering of open issues
1507
- - **`review_this_pr`** _(1.5)_ - PR-comment-ready review primed with the structural diff and verdict
1508
- - **`safely_rename_symbol`** _(1.5)_ - ordered rename + verification checklist via `projscan_impact` blast radius
1509
-
1510
- ### Resources (3, readable on demand)
1511
-
1512
- - `projscan://health` · `projscan://hotspots` · `projscan://structure`
1513
-
1514
- ## Use Cases
1515
-
1516
- - **Onboarding**: Understand any codebase in seconds, not hours
1517
- - **Code reviews**: Run `projscan doctor --format markdown` and paste into PRs
1518
- - **Tech-debt prioritization**: Use `projscan hotspots` to decide what deserves refactoring time
1519
- - **AI-assisted development**: Mount `projscan mcp` in your agent of choice for grounded edits
1520
- - **CI/CD**: Use `projscan ci` to enforce health standards in your pipeline
1521
- - **Security**: Catch committed secrets and `.env` files before they reach production
1522
- - **Consulting**: Quickly assess client projects before diving in
1523
- - **Maintenance**: Track health trends with `projscan diff` across releases
372
+ - [Full guide](docs/GUIDE.md)
373
+ - [First 10 minutes](docs/FIRST-10-MINUTES.md)
374
+ - [Roadmap](docs/ROADMAP.md)
375
+ - [Adoption workflows](docs/examples/adoption-workflows.md)
376
+ - [Swarm coordination](docs/examples/swarm-coordination.md)
377
+ - [Stability policy](docs/STABILITY.md)
378
+ - [Telemetry policy](TELEMETRY.md)
379
+ - [Security policy](SECURITY.md)
1524
380
 
1525
381
  ## Contributing
1526
382
 
1527
- Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. Contributions are accepted under the MIT License and the DCO 1.1 certification described there.
383
+ Read [CONTRIBUTING.md](CONTRIBUTING.md) before opening a PR. Contributions use the MIT License and the DCO 1.1 certification described there.
1528
384
 
1529
- ## Legal and Trust
385
+ ## Legal
1530
386
 
1531
387
  - License: [MIT](LICENSE)
1532
388
  - Disclaimer: [DISCLAIMER.md](DISCLAIMER.md)
@@ -1536,8 +392,6 @@ Contributions are welcome. Please read [CONTRIBUTING.md](CONTRIBUTING.md) before
1536
392
  - Trademark and brand policy: [TRADEMARKS.md](TRADEMARKS.md)
1537
393
  - Third-party notices: [THIRD-PARTY-NOTICES.md](THIRD-PARTY-NOTICES.md)
1538
394
 
1539
- projscan is free and open source. The CLI and MCP server are local-first and do not upload source code or scan results to a projscan service. Anonymous product telemetry is default-off and only runs after explicit opt-in.
1540
-
1541
395
  <p align="center">
1542
396
  <a href="https://www.baseframelabs.com" target="_blank" rel="noopener" title="Part of Baseframe Labs">
1543
397
  <span>part of</span>