projscan 4.9.3 → 4.11.0

package/docs/GUIDE.md

@@ -126,11 +126,25 @@ and a before-edit gate instead of a free-form plan.
 projscan bug-hunt --format json
 projscan preflight --mode before_commit --format json
 projscan evidence-pack --pr-comment
+projscan assess --goal "make this repo safer to ship this week"
+projscan assess --mode fix-first --format markdown
+projscan simulate --plan "split bugHunt.ts into ranking, evidence, and output modules"
 ```
 
 Success criteria: concrete fix targets, manual review gates, and proof commands
 are separated before a reviewer sees the work.
 
+`projscan assess` turns those same signals into Proof Cards with evidence,
+impact, a safe change shape, verification commands, feedback or suppression
+guidance, and a risk delta. Add `--baseline previous-assess.json` to compare
+the current risk delta against a prior run. It does not release, tag, publish,
+or deploy.
+
+`projscan simulate --plan "<change plan>"` is the next step when the safest
+fix shape is a refactor, extraction, or module split. It predicts likely files,
+affected tests, contract surfaces, rollout steps, proof commands, and projected
+risk delta from local evidence. It is read-only and does not execute the plan.
+
 ### Before release-candidate review
 
 ```bash
@@ -234,6 +248,8 @@ When the agent first opens a repo, or before starting a refactor, the question i
 - **`projscan_bug_hunt` / `projscan bug-hunt`** — bug-hunt action queue. Combines doctor issues, preflight, hotspots, and session coordination into ranked actions with verification commands; release-scale-only findings print as manual review/sign-off work while preserving JSON verdict compatibility, and pure hotspot churn stays as watchlist/top-suspect evidence when health and gates are clean.
 - **`projscan_agent_brief` / `projscan agent-brief`** — compact next-agent context packet with focus items, repo context, coordination hints, guardrails, and suggested next actions.
 - **`projscan_quality_scorecard` / `projscan quality-scorecard`** — dimensioned quality view across health, security, tests, maintainability, coordination, top risks, and verification commands.
+- **`projscan_assess` / `projscan assess`** — proof-first assessment. Composes quality-scorecard, bug-hunt, and preflight into Proof Cards with local evidence, impact, a safe fix shape, verification commands, feedback or suppression guidance, and risk delta. Use `projscan assess --goal "make this repo safer to ship this week"` for a broad weekly pass, `projscan assess --mode fix-first --format markdown` when you want one or two next actions instead of a long list, or `--baseline previous-assess.json` to compare against a prior assessment. The command is read-only and does not release, tag, publish, or deploy.
+- **`projscan_simulate` / `projscan simulate`** — risk delta simulator. Evaluates a proposed change plan before editing and returns likely touched files, affected tests, contract surfaces, rollout steps, proof commands, confidence, and projected before/after risk. Use `projscan simulate --plan "split bugHunt.ts into ranking, evidence, and output modules"` before doing a refactor. The command is read-only and does not execute the plan.
 - **`projscan_understand` / `projscan understand`** — cited repo-comprehension surface. Returns repo maps, runtime flow maps, contract maps, change-readiness guidance, verification tiers, unknowns, read-first files, and exact next commands.
 - **`projscan_adoption` / `projscan init team` / `projscan init mcp` / `projscan mcp doctor` / `projscan init policy` / `projscan init github-action` / `projscan recipes` / `projscan first-run` / `projscan telemetry` / `projscan dogfood`** — adoption layer. Returns MCP client config snippets, setup verification, policy starters, PR workflow scaffolding with validated PR comments and block-only enforcement, baseline memory, ownership routing, first-PR onboarding steps, repeatable team-bootstrap and PR-automation recipes, multi-repo dogfood evidence, measured reviewer feedback, default-off telemetry controls, adoption trial reports, and setup diagnostics.
 - **`projscan_release_train` / `projscan release-train`** — product-line readiness planner. Plans upcoming product lines with version, scope, readiness, and next-action evidence.
@@ -551,13 +567,14 @@ Natural follow-up to `projscan hotspots` - once hotspots tells you _which_ file
 projscan ci
 ```
 
-A CI-pipeline-friendly health gate. Runs the full health check and exits with code 1 if the score falls below a threshold. No spinners or banners - clean output for CI logs.
+A CI-pipeline-friendly health gate. Runs the full health check and exits with code 1 if the score falls below a threshold and at least one finding meets the `failOn` severity floor. No spinners or banners - clean output for CI logs.
 
 **Options:**
 
 | Flag               | Description                                      | Default                                                     |
 | ------------------ | ------------------------------------------------ | ----------------------------------------------------------- |
 | `--min-score <n>`  | Minimum passing score (0–100)                    | `minScore` from `.projscanrc`, else 70                      |
+| `--fail-on <severity>` | Lowest severity that can fail a below-threshold gate: `info`, `warning`, or `error` | `failOn` from `.projscanrc`, else `warning` |
 | `--changed-only`   | Gate only on issues in files changed vs base ref | off                                                         |
 | `--base-ref <ref>` | Git base ref for `--changed-only`                | auto (origin/main → origin/master → main → master → HEAD~1) |
 
@@ -566,7 +583,7 @@ A CI-pipeline-friendly health gate. Runs the full health check and exits with co
 ```bash
 $ projscan ci --min-score 80
 
-projscan: B (82/100) - 0 errors, 2 warnings, 1 info - PASS (threshold: 80)
+projscan: B (82/100) - 0 errors, 2 warnings, 1 info - PASS (threshold: 80, failOn: warning)
 ```
 
 <img src="npx%20projscan%20ci%20--min-score%2070.gif" alt="npx projscan ci" width="700">
@@ -574,7 +591,8 @@ projscan: B (82/100) - 0 errors, 2 warnings, 1 info - PASS (threshold: 80)
 **Exit codes:**
 
 - `0` - Score meets or exceeds the threshold
-- `1` - Score is below the threshold
+- `0` - Score is below the threshold but no finding meets the `failOn` floor
+- `1` - Score is below the threshold and at least one finding meets the `failOn` floor
 
 **JSON output** (useful for scripts):
 
@@ -582,6 +600,10 @@ projscan: B (82/100) - 0 errors, 2 warnings, 1 info - PASS (threshold: 80)
 projscan ci --min-score 70 --format json
 ```
 
+Every `ci.issues[]` item keeps the original issue fields and adds
+annotation-friendly fields: `ruleId`, `message`, primary `location`, all
+`locations`, and `remediation` when a fix hint is available.
+
 **SARIF output** (for GitHub Code Scanning or any SARIF consumer):
 
 ```bash
@@ -887,6 +909,9 @@ Use it before broader rollout. The report includes feedback questions for the fi
 ## Health Score
 
 Every `projscan doctor` and `projscan badge` run calculates a health score from 0 to 100 based on detected issues.
+`doctor --format json` and `ci --format json` include `scoreBreakdown` so scripts
+and reviewers can see the base score, per-severity weights, category penalties,
+total penalty, final score, and grade.
 
 **Scoring:**
 
@@ -909,7 +934,8 @@ Every `projscan doctor` and `projscan badge` run calculates a health score from
 The score appears in all output formats:
 
 - **Console**: Shown at the top of the doctor report
-- **JSON**: Included as `health.score` and `health.grade` fields
+- **JSON**: Included as `health.score`, `health.grade`, and `health.scoreBreakdown`
+  fields. CI uses the same structure under `ci.scoreBreakdown`.
 - **Markdown**: Shown as a heading with an auto-generated shields.io badge
 - **HTML**: Shown in the health summary card
 - **SARIF**: Not surfaced directly - SARIF is per-issue, not per-project. The score still drives `ci`'s exit code.
@@ -1005,6 +1031,7 @@ ProjScan loads a project-wide config from one of:
 ```json
 {
   "minScore": 80,
+  "failOn": "warning",
   "baseRef": "origin/main",
   "ignore": ["**/fixtures/**", "**/generated/**"],
   "scan": {
@@ -1013,6 +1040,9 @@ ProjScan loads a project-wide config from one of:
     "offline": false
   },
   "disableRules": ["missing-editorconfig", "large-*"],
+  "suppress": {
+    "hardcoded-secret": ["src/firebase.ts"]
+  },
   "severityOverrides": {
     "missing-prettier": "info"
   },
@@ -1034,12 +1064,14 @@ ProjScan loads a project-wide config from one of:
 | Field                 | Type                                             | Effect                                                                                                                                                        |
 | --------------------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `minScore`            | number (0–100)                                   | Default threshold for `projscan ci`. Clamped to 0–100.                                                                                                        |
+| `failOn`              | `'info' \| 'warning' \| 'error'`                 | Lowest severity that can fail a below-threshold `projscan ci` gate. Default `warning`; set `info` for legacy strictness or `error` for error-only blocking. |
 | `baseRef`             | string                                           | Default base ref for `--changed-only`.                                                                                                                        |
 | `ignore`              | string[]                                         | Extra glob patterns added to the built-in ignore list (`node_modules`, `.git`, `dist`, `build`, `coverage`, `.next`, `.nuxt`, `.cache`, `.turbo`, `.output`). |
 | `scan.includeIgnored` | boolean                                          | Explicitly include files hidden by Git ignore rules. Default `false`.                                                                                         |
 | `scan.scanEnvValues`  | boolean                                          | Explicitly read `.env*` contents during secret-pattern checks. Default `false`; `.env` files are path-only.                                                   |
 | `scan.offline`        | boolean                                          | Block projscan network-capable features: telemetry sending, `audit`, registry checks, and optional semantic model loading. Default `false`.                   |
 | `disableRules`        | string[]                                         | Silence rules by id. Exact match (`missing-prettier`) or wildcard prefix (`large-*`).                                                                         |
+| `suppress`            | `Record<string, string[]>`                       | Silence a rule only for matching paths/globs, for example `{ "hardcoded-secret": ["src/firebase.ts"] }`. Other rules still run on that file.                  |
 | `severityOverrides`   | `Record<string, 'info' \| 'warning' \| 'error'>` | Remap a rule's severity. Useful for downgrading project-specific false positives without disabling them.                                                      |
 | `reportPolicies`      | `Record<string, { reportScope?: string[]; redactPaths?: boolean }>` | Named evidence export presets selected with `--report-policy <name>` on `analyze`, `doctor`, and `ci`.                                      |
 | `hotspots.limit`      | number (1–100)                                   | Default limit for `projscan hotspots`.                                                                                                                        |
@@ -1047,6 +1079,12 @@ ProjScan loads a project-wide config from one of:
 
 Invalid JSON in a discovered config file is a hard error - projscan exits rather than silently ignoring it.
 
+Use inline suppressions for a single confirmed false positive:
+
+```ts
+const firebaseKey = "AIza..." // projscan-ignore-line hardcoded-secret -- Firebase web keys are public identifiers
+```
+
 ### Embedded config in `package.json`
 
 If you prefer to keep everything in `package.json`:
@@ -1361,6 +1399,8 @@ _Structural / agent-native:_
 - `projscan_bug_hunt` — prioritized bug-hunt action queue with per-action verification.
 - `projscan_agent_brief` — compact next-agent context packet with focus items, guardrails, repo context, and suggested next actions.
 - `projscan_quality_scorecard` — dimensioned quality view with top risks and verification commands.
+- `projscan_assess` — proof-first assessment with Proof Cards, risk delta, and fix-first guidance.
+- `projscan_simulate` — risk delta simulator for proposed change plans before editing.
 - `projscan_adoption` — adoption helper for MCP client snippets, MCP setup doctor, agent workflow recipes, and first-run diagnostics.
 - `projscan_release_train` — product-line readiness plan with scope and next-action evidence.
 - `projscan_evidence_pack` — approval packet with planning, bug-hunt, workplan, preflight, changelog, and website prompt evidence.
@@ -1564,8 +1604,10 @@ If you'd rather skip Code Scanning, `projscan init github-action` writes a pull-
 The `ci` command is purpose-built for pipelines:
 
 ```bash
-projscan ci                                 # Fail if score < 70 (default)
+projscan ci                                 # Fail if score < 70 and warning/error findings exist
 projscan ci --min-score 80                  # Custom threshold
+projscan ci --fail-on info                  # Legacy strictness: info can fail the gate
+projscan ci --fail-on error                 # Only errors can fail a below-threshold gate
 projscan ci --changed-only                  # Gate only on PR diff
 projscan ci --format json                   # JSON output for scripts
 projscan ci --format sarif > projscan.sarif # SARIF for any consumer
@@ -1577,9 +1619,15 @@ projscan ci --format sarif > projscan.sarif # SARIF for any consumer
 result=$(projscan ci --min-score 0 --format json)
 pass=$(echo "$result" | jq '.ci.pass')
 score=$(echo "$result" | jq '.ci.score')
-echo "Score: $score, Pass: $pass"
+fail_on=$(echo "$result" | jq -r '.ci.failOn')
+echo "Score: $score, Pass: $pass, FailOn: $fail_on"
 ```
 
+For PR annotation tooling, read `.ci.issues[]`. Each issue includes `ruleId`,
+`severity`, `message`, primary `location`, all `locations`, and `remediation`
+when available. Gate metadata lives at `.ci.failOn`, `.ci.scorePass`, and
+`.ci.severityFloorMet`.
+
 ### Tracking health over time in CI
 
 Combine `ci` with `diff` to track regressions:
@@ -1675,7 +1723,7 @@ src/
 ├── mcp/
 │   ├── server.ts                # MCP server factory and JSON-RPC request orchestration
 │   ├── serverStdio.ts           # stdio transport loop for the CLI entry point
-│   ├── tools.ts                 # 41 MCP tools (barrel; per-tool files under tools/)
+│   ├── tools.ts                 # MCP tools barrel; per-tool files live under tools/
 │   ├── tokenBudget.ts           # Record-aware response truncator
 │   ├── pagination.ts            # Cursor-based pagination (opaque base64 + checksum)
 │   ├── progress.ts              # notifications/progress plumbing

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "4.9.3",
+  "version": "4.11.0",
   "description": "Local code intelligence for agent-assisted engineering. Focused daily workflows for repo orientation before edits, proof before handoff or commit, and release-candidate review, with AST-backed evidence through an MCP server and CLI. Runs locally by default.",
   "type": "module",
   "main": "./dist/index.js",