projscan 4.11.0 → 4.11.1

package/README.md

@@ -102,6 +102,8 @@ You get Proof Cards: each recommendation carries local evidence, impact, a safe
 
 Use the risk delta simulator before a refactor or extraction. It predicts likely touched files, affected tests, contract surfaces, rollout steps, proof commands, and before/after risk from local evidence. It is read-only: it does not edit files, run the plan, release, tag, publish, or deploy.
 
+<img src="docs/projscan-proof-cards.png" alt="projscan assess showing a Proof Card with evidence, impact, safe change shape, verification commands, feedback path, and risk delta" width="760">
+
 Success criteria: the team sees the one or two highest-value fixes, why they matter, how to prove them, and whether ship-readiness still needs caution or review.
 
 ## Mission Control
@@ -143,6 +145,16 @@ npm run docs:screenshots
 npm run docs:demos
 ```
 
+## 4.11.1 Notes
+
+4.11.1 is a public README media refresh for the proof-first release:
+
+- Added a dedicated Proof Cards screenshot for `projscan assess` and
+  `projscan simulate`.
+- Regenerated README screenshots so public media shows the current 47-tool MCP
+  surface.
+- Updated website handoff guidance to use immutable `v4.11.1` media URLs.
+
 ## 4.11.0 Notes
 
 4.11.0 is the proof-first engineering command center release:
@@ -183,45 +195,45 @@ npx -y projscan mcp --watch
 
 ### Agent Questions
 
-| Agent question                               | CLI or MCP route                                                                 |
-| -------------------------------------------- | -------------------------------------------------------------------------------- |
-| Which files implement auth?                  | `projscan search "auth" --format json`                                           |
-| Who imports this file?                       | `projscan semantic-graph --query importers --file src/auth/jwt.ts --format json` |
-| What breaks if I rename this symbol?         | `projscan impact --symbol buildCodeGraph --format json`                          |
-| What should I fix first?                     | `projscan bug-hunt --format json`                                                |
-| What is risky and worth fixing this week?    | `projscan assess --goal "make this repo safer to ship this week"`                |
+| Agent question                               | CLI or MCP route                                                                         |
+| -------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| Which files implement auth?                  | `projscan search "auth" --format json`                                                   |
+| Who imports this file?                       | `projscan semantic-graph --query importers --file src/auth/jwt.ts --format json`         |
+| What breaks if I rename this symbol?         | `projscan impact --symbol buildCodeGraph --format json`                                  |
+| What should I fix first?                     | `projscan bug-hunt --format json`                                                        |
+| What is risky and worth fixing this week?    | `projscan assess --goal "make this repo safer to ship this week"`                        |
 | Is this refactor worth doing?                | `projscan simulate --plan "split bugHunt.ts into ranking, evidence, and output modules"` |
-| Which files have high risk and low coverage? | `projscan coverage --format json`                                                |
-| What should my agent do next?                | `projscan workplan --format json`                                                |
-| Which proof belongs in this PR?              | `projscan evidence-pack --pr-comment`                                            |
-| Is this branch ready to merge?               | `projscan preflight --mode before_merge --format json`                           |
+| Which files have high risk and low coverage? | `projscan coverage --format json`                                                        |
+| What should my agent do next?                | `projscan workplan --format json`                                                        |
+| Which proof belongs in this PR?              | `projscan evidence-pack --pr-comment`                                                    |
+| Is this branch ready to merge?               | `projscan preflight --mode before_merge --format json`                                   |
 
 ## Command Map
 
-| Command                   | Use it when you need                                                       |
-| ------------------------- | -------------------------------------------------------------------------- |
-| `projscan start`          | first-60-seconds orientation, routing, and Mission Control                 |
-| `projscan understand`     | cited repo map, runtime flows, public contracts, and change readiness      |
-| `projscan preflight`      | proceed, caution, or block gate for edit, commit, or merge                 |
+| Command                   | Use it when you need                                                        |
+| ------------------------- | --------------------------------------------------------------------------- |
+| `projscan start`          | first-60-seconds orientation, routing, and Mission Control                  |
+| `projscan understand`     | cited repo map, runtime flows, public contracts, and change readiness       |
+| `projscan preflight`      | proceed, caution, or block gate for edit, commit, or merge                  |
 | `projscan assess`         | proof-first assessment with Proof Cards, risk delta, and fix-first guidance |
 | `projscan simulate`       | risk delta simulator for a proposed change plan before editing              |
-| `projscan evidence-pack`  | PR-ready proof with risks, owners, and next commands                       |
-| `projscan bug-hunt`       | ranked fix queue from health, hotspots, session, and preflight evidence    |
-| `projscan workplan`       | ordered agent tasks with proof and handoff text                            |
-| `projscan doctor`         | project health, tooling gaps, dead code, and supply-chain signals          |
-| `projscan review`         | one-call PR review from structural diff, risk, cycles, functions, and deps |
-| `projscan impact`         | blast radius for a file or symbol before rename, delete, or upgrade        |
-| `projscan semantic-graph` | imports, exports, importers, symbol definitions, and package importers     |
-| `projscan dataflow`       | framework-aware source-to-sink risks                                       |
-| `projscan hotspots`       | churn, complexity, ownership, and coverage risk ranking                    |
-| `projscan coverage`       | high-risk files with weak test coverage                                    |
-| `projscan dependencies`   | dependency inventory, license summary, and risk notes                      |
-| `projscan upgrade <pkg>`  | offline upgrade impact from changelog and importer evidence                |
-| `projscan audit`          | normalized `npm audit` findings and SARIF                                  |
-| `projscan coordinate`     | collisions, claims, and merge-risk across worktrees                        |
-| `projscan plugin`         | local analyzer and reporter plugin workflow                                |
-| `projscan privacy-check`  | local scan boundary, telemetry, ignore rules, and network-capable paths    |
-| `projscan mcp`            | MCP server over stdio                                                      |
+| `projscan evidence-pack`  | PR-ready proof with risks, owners, and next commands                        |
+| `projscan bug-hunt`       | ranked fix queue from health, hotspots, session, and preflight evidence     |
+| `projscan workplan`       | ordered agent tasks with proof and handoff text                             |
+| `projscan doctor`         | project health, tooling gaps, dead code, and supply-chain signals           |
+| `projscan review`         | one-call PR review from structural diff, risk, cycles, functions, and deps  |
+| `projscan impact`         | blast radius for a file or symbol before rename, delete, or upgrade         |
+| `projscan semantic-graph` | imports, exports, importers, symbol definitions, and package importers      |
+| `projscan dataflow`       | framework-aware source-to-sink risks                                        |
+| `projscan hotspots`       | churn, complexity, ownership, and coverage risk ranking                     |
+| `projscan coverage`       | high-risk files with weak test coverage                                     |
+| `projscan dependencies`   | dependency inventory, license summary, and risk notes                       |
+| `projscan upgrade <pkg>`  | offline upgrade impact from changelog and importer evidence                 |
+| `projscan audit`          | normalized `npm audit` findings and SARIF                                   |
+| `projscan coordinate`     | collisions, claims, and merge-risk across worktrees                         |
+| `projscan plugin`         | local analyzer and reporter plugin workflow                                 |
+| `projscan privacy-check`  | local scan boundary, telemetry, ignore rules, and network-capable paths     |
+| `projscan mcp`            | MCP server over stdio                                                       |
 
 Run the generated command help when you need flags:
 
@@ -285,7 +297,7 @@ Use `suppress` for a known false positive in a specific path without disabling
 the rule everywhere. For one line, add an inline directive next to the value:
 
 ```ts
-const firebaseKey = "AIza..." // projscan-ignore-line hardcoded-secret -- Firebase web keys are public identifiers
+const firebaseKey = 'AIza...'; // projscan-ignore-line hardcoded-secret -- Firebase web keys are public identifiers
 ```
 
 Config docs live in [docs/GUIDE.md](docs/GUIDE.md#configuration-projscanrc).
@@ -394,7 +406,7 @@ Supply-chain scanners may flag package strings or APIs used by `git`, `npm audit
 
 ## Install Notes
 
-`projscan@4.11.0` has seven direct runtime dependencies:
+`projscan@4.11.1` has seven direct runtime dependencies:
 
 - `@babel/parser`
 - `@babel/types`
@@ -404,7 +416,7 @@ Supply-chain scanners may flag package strings or APIs used by `git`, `npm audit
 - `ora`
 - `web-tree-sitter`
 
-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.11.0. Open an issue with the warning text if npm reports install scripts from `projscan@latest`, or run `projscan feedback intake --text "<warning text>" --format json` to turn it into a focused setup-trust task.
+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.11.1. Open an issue with the warning text if npm reports install scripts from `projscan@latest`, or run `projscan feedback intake --text "<warning text>" --format json` to turn it into a focused setup-trust task.
 
 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`.
 

package/dist/projscan-sbom.cdx.json

@@ -1,23 +1,23 @@
 {
   "bomFormat": "CycloneDX",
   "specVersion": "1.5",
-  "serialNumber": "urn:uuid:bd2ad4e4-033a-46f3-bbb7-1b717665131f",
+  "serialNumber": "urn:uuid:ac1a1fd3-2c78-4830-8579-508d0b0ff5e9",
   "version": 1,
   "metadata": {
-    "timestamp": "2026-06-21T21:06:26.004Z",
+    "timestamp": "2026-06-22T06:58:43.839Z",
     "tools": [
       {
         "vendor": "projscan",
         "name": "projscan-sbom-generator",
-        "version": "4.11.0"
+        "version": "4.11.1"
       }
     ],
     "component": {
       "type": "application",
-      "bom-ref": "pkg:npm/projscan@4.11.0",
+      "bom-ref": "pkg:npm/projscan@4.11.1",
       "name": "projscan",
-      "version": "4.11.0",
-      "purl": "pkg:npm/projscan@4.11.0"
+      "version": "4.11.1",
+      "purl": "pkg:npm/projscan@4.11.1"
     }
   },
   "components": [

package/dist/tool-manifest.json

@@ -1,8 +1,8 @@
 {
   "name": "projscan",
-  "version": "4.11.0",
+  "version": "4.11.1",
   "mcpProtocolVersion": null,
-  "generatedAt": "2026-06-21T21:06:32.779Z",
+  "generatedAt": "2026-06-22T06:58:50.868Z",
   "toolCount": 47,
   "tools": [
     {

package/docs/demos/projscan-4-1-demo.html

@@ -377,6 +377,109 @@
         background: var(--red);
       }
 
+      .assess {
+        padding-top: 74px;
+      }
+
+      .assess-header {
+        display: grid;
+        grid-template-columns: minmax(0, 0.82fr) minmax(0, 1.18fr);
+        gap: 24px;
+        align-items: end;
+        margin-bottom: 24px;
+      }
+
+      .assess-header h2 {
+        margin-bottom: 10px;
+        font-size: 44px;
+        line-height: 1.06;
+        letter-spacing: 0;
+      }
+
+      .assess-header p {
+        margin-bottom: 0;
+        color: var(--muted);
+        font-size: 18px;
+      }
+
+      .proof-card-grid {
+        display: grid;
+        grid-template-columns: minmax(0, 0.95fr) minmax(0, 1.05fr);
+        gap: 22px;
+      }
+
+      .proof-card {
+        min-height: 470px;
+        padding: 24px;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        background: var(--panel);
+      }
+
+      .proof-card h3 {
+        margin-bottom: 8px;
+        font-size: 30px;
+        line-height: 1.12;
+        letter-spacing: 0;
+      }
+
+      .proof-card p {
+        margin-bottom: 18px;
+        color: var(--muted);
+        font-size: 15px;
+      }
+
+      .evidence-list {
+        display: grid;
+        gap: 10px;
+      }
+
+      .evidence-item {
+        display: grid;
+        grid-template-columns: 118px minmax(0, 1fr);
+        gap: 12px;
+        padding: 13px 0;
+        border-top: 1px solid var(--line);
+        font-size: 14px;
+      }
+
+      .evidence-item strong {
+        color: var(--ink);
+      }
+
+      .evidence-item span {
+        color: var(--muted);
+      }
+
+      .delta-row {
+        display: grid;
+        grid-template-columns: repeat(3, minmax(0, 1fr));
+        gap: 10px;
+        margin-top: 18px;
+      }
+
+      .delta {
+        min-height: 82px;
+        padding: 13px;
+        border: 1px solid var(--line);
+        border-radius: 8px;
+        background: #fbf7ef;
+      }
+
+      .delta strong {
+        display: block;
+        margin-bottom: 5px;
+        font-size: 24px;
+        line-height: 1;
+      }
+
+      .delta span {
+        color: var(--muted);
+        font-size: 12px;
+        font-weight: 800;
+        text-transform: uppercase;
+      }
+
       @media (max-width: 980px) {
         .page {
           width: min(100% - 32px, 760px);
@@ -385,6 +488,8 @@
 
         .hero,
         .proof-header,
+        .assess-header,
+        .proof-card-grid,
         .workflow,
         .grid {
           grid-template-columns: 1fr;
@@ -408,7 +513,11 @@
       }
 
       body.proof-only .hero,
-      body.proof-only .grid {
+      body.proof-only .grid,
+      body.proof-only .assess,
+      body.assess-only .hero,
+      body.assess-only .grid,
+      body.assess-only .proof {
         display: none;
       }
 
@@ -419,6 +528,14 @@
       body.proof-only .proof-header {
         margin-top: 0;
       }
+
+      body.assess-only .assess {
+        padding-top: 0;
+      }
+
+      body.assess-only .assess-header {
+        margin-top: 0;
+      }
     </style>
   </head>
   <body>
@@ -448,7 +565,7 @@
               <span>mission and proof</span>
             </div>
             <div class="metric">
-              <strong>45</strong>
+              <strong>47</strong>
               <span>MCP tools</span>
             </div>
             <div class="metric">
@@ -617,11 +734,106 @@
           </div>
         </div>
       </section>
+
+      <section class="assess" id="assess" aria-label="Proof Cards assessment view">
+        <div class="assess-header">
+          <div>
+            <p class="eyebrow">Proof-first assessment</p>
+            <h2>Pick the safest next fix.</h2>
+          </div>
+          <p>
+            <code>projscan assess</code> turns local quality, bug-hunt, and preflight evidence into
+            Proof Cards. Each card names the risk, the safest change shape, and the commands that
+            prove the risk went down.
+          </p>
+        </div>
+
+        <div class="proof-card-grid">
+          <section class="terminal compact-terminal" aria-label="Assess terminal output">
+            <div class="terminal-bar">
+              <span class="dot red"></span>
+              <span class="dot amber"></span>
+              <span class="dot green"></span>
+              <span class="terminal-title">projscan assess --mode fix-first</span>
+            </div>
+            <div class="terminal-body">
+              <span class="line"
+                ><span class="prompt">$</span>
+                <span class="cmd">projscan assess --mode fix-first --format markdown</span></span
+              >
+              <span class="line dim">Proof-first assessment</span>
+              <span class="line">&nbsp;</span>
+              <span class="line term-heading">Fix first: maintainability hotspot</span>
+              <span class="line">src/core/bugHunt.ts combines ranking, evidence, and output.</span>
+              <span class="line success">Confidence: high</span>
+              <span class="line notice">Risk delta: 76 -> 61 if split behind tests</span>
+              <span class="line">&nbsp;</span>
+              <span class="line term-heading">Proof commands</span>
+              <span class="line success">npm run typecheck</span>
+              <span class="line success">npm run lint</span>
+              <span class="line success">vitest tests/core/bugHunt.test.ts</span>
+              <span class="line">&nbsp;</span>
+              <span class="line term-heading">Simulate before editing</span>
+              <span class="line notice"
+                >projscan simulate --plan "split bugHunt.ts into ranking..."</span
+              >
+            </div>
+          </section>
+
+          <article class="proof-card" aria-label="Proof Card">
+            <span class="label blue">Proof Card</span>
+            <h3>Maintainability hotspot</h3>
+            <p>
+              Fix the extraction only when local evidence shows lower coupling and focused tests can
+              prove behavior stayed stable.
+            </p>
+            <div class="evidence-list">
+              <div class="evidence-item">
+                <strong>Evidence</strong>
+                <span>high churn, high complexity, broad imports, direct bug-hunt tests</span>
+              </div>
+              <div class="evidence-item">
+                <strong>Impact</strong>
+                <span>bug ranking, MCP findings, release review, PR evidence packs</span>
+              </div>
+              <div class="evidence-item">
+                <strong>Safe shape</strong>
+                <span>extract ranking, evidence, and markdown output behind existing tests</span>
+              </div>
+              <div class="evidence-item">
+                <strong>Verify</strong>
+                <span>typecheck, lint, focused Vitest, then bug-hunt smoke</span>
+              </div>
+              <div class="evidence-item">
+                <strong>Feedback</strong>
+                <span>accept, suppress, or feed false-positive notes back into trust memory</span>
+              </div>
+            </div>
+            <div class="delta-row" aria-label="Risk delta">
+              <div class="delta">
+                <strong>76</strong>
+                <span>before risk</span>
+              </div>
+              <div class="delta">
+                <strong>61</strong>
+                <span>after risk</span>
+              </div>
+              <div class="delta">
+                <strong>3</strong>
+                <span>proof commands</span>
+              </div>
+            </div>
+          </article>
+        </div>
+      </section>
     </main>
     <script>
       if (window.location.hash === '#proof') {
         document.body.classList.add('proof-only');
       }
+      if (window.location.hash === '#assess') {
+        document.body.classList.add('assess-only');
+      }
       document.documentElement.dataset.ready = 'true';
     </script>
   </body>

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "4.11.0",
+  "version": "4.11.1",
   "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",
@@ -25,6 +25,7 @@
     "docs/examples/swarm-coordination.md",
     "docs/projscan-mission-control.png",
     "docs/projscan-mission-control.gif",
+    "docs/projscan-proof-cards.png",
     "docs/projscan-proof-router.png",
     "docs/projscan-mission-proof.gif",
     "docs/examples/plugins",

package/scripts/capture-readme-assets.mjs

@@ -24,6 +24,12 @@ const captures = [
     output: path.join(repoRoot, 'docs', 'projscan-proof-router.png'),
     viewport: '1440,760',
   },
+  {
+    name: 'Proof Cards assessment',
+    url: `${pathToFileURL(demoPath).href}#assess`,
+    output: path.join(repoRoot, 'docs', 'projscan-proof-cards.png'),
+    viewport: '1440,820',
+  },
 ];
 
 for (const capture of captures) {