projscan 4.3.1 → 4.5.0

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

@@ -34,8 +34,13 @@
         background: var(--paper);
         color: var(--ink);
         font-family:
-          Inter, ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont,
-          "Segoe UI", sans-serif;
+          Inter,
+          ui-sans-serif,
+          system-ui,
+          -apple-system,
+          BlinkMacSystemFont,
+          'Segoe UI',
+          sans-serif;
         line-height: 1.45;
       }
 
@@ -181,8 +186,7 @@
 
       .terminal-body {
         padding: 26px;
-        font-family:
-          "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
+        font-family: 'SFMono-Regular', Consolas, 'Liberation Mono', Menlo, monospace;
         font-size: 15px;
       }
 
@@ -425,9 +429,9 @@
             <p class="eyebrow">Mission Outcome Loop</p>
             <h1>Resume from real proof.</h1>
             <p class="lead">
-              projscan routes a developer goal, saves the mission, reads the
-              proof state, and tells the next agent what changed, what remains,
-              and whether the work is ready for version review.
+              projscan routes a developer goal, saves the mission, reads the proof state, and tells
+              the next agent what changed, what remains, and whether the work is ready for version
+              review.
             </p>
             <div class="pills" aria-label="Product capabilities">
               <span class="pill">Mission Control</span>
@@ -464,64 +468,41 @@
           <div class="terminal-body">
             <span class="line"
               ><span class="prompt">$</span>
-              <span class="cmd"
-                >projscan start --mission .projscan/mission</span
-              ></span
+              <span class="cmd">projscan start --mission .projscan/mission</span></span
             >
             <span class="line dim">ProjScan Mission Control</span>
             <span class="line">Mission: .projscan/mission</span>
             <span class="line">Status: <span class="success">passed</span></span>
             <span class="line"
-              >Outcome:
-              <span class="notice">proof passed after 3 commands</span></span
-            >
-            <span class="line dim"
-              >read proof-logs/summary.json and status.jsonl</span
+              >Outcome: <span class="notice">proof passed after 3 commands</span></span
             >
+            <span class="line dim">read proof-logs/summary.json and status.jsonl</span>
 
             <div class="term-section">
               <span class="line term-heading">What Changed</span>
-              <span class="line"
-                >- Mission proof passed after 3 command(s).</span
-              >
-              <span class="line"
-                >- 1 reviewer decision recorded.</span
-              >
+              <span class="line">- Mission proof passed after 3 command(s).</span>
+              <span class="line">- 1 reviewer decision recorded.</span>
               <span class="line">- 0 failed gates remain.</span>
             </div>
 
             <div class="term-section">
               <span class="line term-heading">What Remains</span>
-              <span class="line success"
-                >Run ./review.sh and choose a reviewer reply.</span
-              >
-              <span class="line success"
-                >Version candidate: review_candidate</span
-              >
+              <span class="line success">Run ./review.sh and choose a reviewer reply.</span>
+              <span class="line success">Version candidate: review_candidate</span>
             </div>
 
             <div class="term-section">
               <span class="line term-heading">Outcome Commands</span>
-              <span class="line success"
-                >projscan start --mission .projscan/mission</span
-              >
-              <span class="line success"
-                >projscan mission-proof --mission .projscan/mission</span
-              >
-              <span class="line success"
-                >projscan mission-proof --baseline manual-runs.json</span
-              >
+              <span class="line success">projscan start --mission .projscan/mission</span>
+              <span class="line success">projscan mission-proof --mission .projscan/mission</span>
+              <span class="line success">projscan mission-proof --baseline manual-runs.json</span>
               <span class="line dim">all source stays local</span>
             </div>
 
             <div class="term-section">
               <span class="line term-heading">Proof Evidence</span>
-              <span class="line success"
-                >proof-logs/summary.json: passed</span
-              >
-              <span class="line success"
-                >proof-logs/status.jsonl: 3 rows</span
-              >
+              <span class="line success">proof-logs/summary.json: passed</span>
+              <span class="line success">proof-logs/status.jsonl: 3 rows</span>
             </div>
 
             <div class="term-section">
@@ -540,27 +521,25 @@
           <span class="label green">Goal routing</span>
           <h2>Ask in plain language.</h2>
           <p>
-            Route privacy, merge readiness, refactor risk, local setup,
-            ownership, dependency, release, and handoff questions to the right
-            command with matched keywords and confidence.
+            Route privacy, merge readiness, refactor risk, local setup, ownership, dependency,
+            release, and handoff questions to the right command with matched keywords and
+            confidence.
           </p>
         </article>
         <article class="card">
           <span class="label blue">Outcome resume</span>
           <h2>Start from saved proof.</h2>
           <p>
-            <code>projscan start --mission</code> reads the bundle proof state
-            and gives the next agent a focused "what changed / what remains"
-            handoff.
+            <code>projscan start --mission</code> reads the bundle proof state and gives the next
+            agent a focused "what changed / what remains" handoff.
           </p>
         </article>
         <article class="card">
           <span class="label amber">Proof report</span>
           <h2>Measure the saved work.</h2>
           <p>
-            <code>projscan mission-proof</code> reports proof completion,
-            reviewer approvals, reruns, failed gates, time saved, and local
-            risk avoided.
+            <code>projscan mission-proof</code> reports proof completion, reviewer approvals,
+            reruns, failed gates, time saved, and local risk avoided.
           </p>
         </article>
       </section>
@@ -572,9 +551,9 @@
             <h2>Close the loop.</h2>
           </div>
           <p>
-            Developers and agents can resume from a saved mission bundle,
-            summarize pass/fail evidence, and compare local proof against a
-            manual baseline without sending source code anywhere.
+            Developers and agents can resume from a saved mission bundle, summarize pass/fail
+            evidence, and compare local proof against a manual baseline without sending source code
+            anywhere.
           </p>
         </div>
 
@@ -590,27 +569,18 @@
               <span class="line"
                 ><span class="prompt">$</span>
                 <span class="cmd"
-                  >projscan mission-proof --mission .projscan/mission --format
-                  json</span
+                  >projscan mission-proof --mission .projscan/mission --format json</span
                 ></span
               >
               <span class="line dim">Local proof summary</span>
               <span class="line">&nbsp;</span>
               <span class="line term-heading">{"passed":1,"failed":0,</span>
-              <span class="line success"
-                >&nbsp;"reruns":0,"reviewerApprovals":1}</span
-              >
+              <span class="line success">&nbsp;"reruns":0,"reviewerApprovals":1}</span>
               <span class="line">&nbsp;</span>
               <span class="line term-heading">Risk avoided</span>
-              <span class="line success"
-                >- proof gate passed before release</span
-              >
-              <span class="line success"
-                >- version review is safe to request</span
-              >
-              <span class="line notice"
-                >Next: projscan start --mission .projscan/mission</span
-              >
+              <span class="line success">- proof gate passed before release</span>
+              <span class="line success">- version review is safe to request</span>
+              <span class="line notice">Next: projscan start --mission .projscan/mission</span>
             </div>
           </section>
 
@@ -619,32 +589,29 @@
               <span class="tag green">Verify</span>
               <span>
                 <strong>Outcome resume</strong>
-                <code>--mission</code> reads <code>summary.json</code>, status
-                rows, and reviewer decisions.
+                <code>--mission</code> reads <code>summary.json</code>, status rows, and reviewer
+                decisions.
               </span>
             </div>
             <div class="signal">
               <span class="tag blue">MCP</span>
               <span>
                 <strong>MCP start input</strong>
-                <code>mission_dir</code> carries the same proof outcome to
-                agent clients.
+                <code>mission_dir</code> carries the same proof outcome to agent clients.
               </span>
             </div>
             <div class="signal">
               <span class="tag amber">List</span>
               <span>
                 <strong>Proof summary</strong>
-                <code>mission-proof</code> reports completion, reruns, failed
-                gates, and approvals.
+                <code>mission-proof</code> reports completion, reruns, failed gates, and approvals.
               </span>
             </div>
             <div class="signal">
               <span class="tag red">Gate</span>
               <span>
                 <strong>Version review</strong>
-                Outcome data says whether to request review or keep fixing
-                failed proof.
+                Outcome data says whether to request review or keep fixing failed proof.
               </span>
             </div>
           </div>
@@ -652,10 +619,10 @@
       </section>
     </main>
     <script>
-      if (window.location.hash === "#proof") {
-        document.body.classList.add("proof-only");
+      if (window.location.hash === '#proof') {
+        document.body.classList.add('proof-only');
       }
-      document.documentElement.dataset.ready = "true";
+      document.documentElement.dataset.ready = 'true';
     </script>
   </body>
 </html>

package/docs/examples/adoption-workflows.md

@@ -0,0 +1,128 @@
+# Adoption Workflows
+
+These examples turn projscan from a one-off scanner into a repeatable team
+habit. They are written around the personas in `docs/PERSONAS.md`: skeptical
+senior reviewer, platform lead, product engineer, release owner, and security
+reviewer.
+
+## 1. Agent Orchestration
+
+Use this when a team is standardizing how agents start work, prove changes, and
+hand off safely.
+
+```bash
+projscan privacy-check --offline
+projscan start --intent "add billing webhook support" --format json
+projscan preflight --mode before_edit --format json
+projscan workplan --mode before_edit --format json
+projscan agent-brief --intent "handoff billing webhook work" --format json
+```
+
+Decision loop:
+
+| Persona | Reads | Decision |
+| --- | --- | --- |
+| Product engineer | `start.missionControl.readyActions` | What can I run now? |
+| Platform lead | `preflight.verdict`, coordination hints | Is parallel work safe? |
+| Senior reviewer | proof commands and done criteria | Is the handoff reviewable? |
+
+If the repo uses AgentLoopKit or AgentFlight, `projscan start` surfaces the
+local harness proof commands when their config files exist. Run those commands
+as part of the handoff proof:
+
+```bash
+npm exec agentloop -- status
+npm exec agentflight -- verify
+```
+
+## 2. Package Ownership
+
+Use this when a monorepo or platform team needs to know who owns a dependency,
+route review, or plan an upgrade.
+
+```bash
+projscan dependencies --format json
+projscan semantic-graph --query package_importers --symbol fastapi --format json
+projscan upgrade fastapi --format json
+projscan agent-brief --intent "handoff package ownership for fastapi" --format json
+```
+
+For Node packages, `upgrade` reads local `package.json`, `node_modules`, local
+CHANGELOG files, and importer evidence. For Python packages, it reads
+`pyproject.toml`, `setup.cfg`, `setup.py`, root `requirements*.txt` files,
+Poetry lockfiles, and pinned root requirements, then returns declared scope,
+current-version source, drift, and Python importers.
+
+Decision loop:
+
+| Persona | Reads | Decision |
+| --- | --- | --- |
+| Package owner | importer list | Which app or package needs review? |
+| Release owner | drift and importer count | Is this safe for the current train? |
+| Security reviewer | audit/dependencies plus importer evidence | Is a forced update justified? |
+
+## 3. Custom Policy Plugin
+
+Use this when team-specific rules matter more than generic static analysis,
+such as service ownership, route policy, or security-sensitive directories.
+
+```bash
+projscan plugin init --kind analyzer --name team-policy
+projscan plugin validate .projscan-plugins/team-policy.projscan-plugin.json
+projscan plugin test .projscan-plugins/team-policy.projscan-plugin.json
+PROJSCAN_PLUGINS_PREVIEW=1 projscan doctor --format json
+```
+
+Start from packaged examples:
+
+- `docs/examples/plugins/policy.projscan-plugin.json`
+- `docs/examples/plugins/api-route-ownership.projscan-plugin.json`
+- `docs/examples/plugins/security-sensitive-files.projscan-plugin.json`
+- `docs/examples/plugins/team-radar.projscan-plugin.json`
+
+Decision loop:
+
+| Persona | Reads | Decision |
+| --- | --- | --- |
+| Platform lead | plugin diagnostics | Is the rule trusted enough for CI? |
+| Security reviewer | emitted issues | Does the policy catch the right risky paths? |
+| Product engineer | suggested action | Can this be fixed without tribal context? |
+
+## 4. Shareable Evidence With Path Controls
+
+Use this when a team wants to share a health or CI artifact without exposing
+repo layout or sensitive paths.
+
+```bash
+projscan analyze --report-scope src/api --redact-paths --format json > reports/api-analysis.json
+projscan doctor --report-scope src/api --redact-paths --format markdown > reports/api-health.md
+projscan ci --report-scope src/api --redact-paths --format sarif > reports/api.sarif
+```
+
+`--report-scope` keeps only issues and files under the listed repo-relative
+paths. `--redact-paths` replaces file paths with stable labels such as
+`redacted-path-1`, so reviewers can correlate evidence without seeing the
+original repo structure.
+
+When the same evidence shape is reused by a partner review, security check, or
+release train, put it in config and select it by name:
+
+```json
+{
+  "reportPolicies": {
+    "apiEvidence": {
+      "reportScope": ["src/api"],
+      "redactPaths": true
+    }
+  }
+}
+```
+
+```bash
+projscan analyze --report-policy apiEvidence --format json > reports/api-analysis.json
+projscan doctor --report-policy apiEvidence --format markdown > reports/api-health.md
+projscan ci --report-policy apiEvidence --format sarif > reports/api.sarif
+```
+
+Use direct `--report-scope` or `--redact-paths` flags with `--report-policy` for
+one-off overrides without changing the shared config preset.

package/docs/examples/plugins/graph-context.mjs

@@ -16,8 +16,7 @@ export default {
       {
         id: 'graph-context-summary',
         title: 'Graph context available',
-        description:
-          `Plugin received ${fileCount} file(s), ${functionCount} function(s), ${callEdges} semantic edge(s), and ${dataflow.riskCount} dataflow risk(s).`,
+        description: `Plugin received ${fileCount} file(s), ${functionCount} function(s), ${callEdges} semantic edge(s), and ${dataflow.riskCount} dataflow risk(s).`,
         severity,
         category: 'architecture',
         fixAvailable: false,

package/docs/examples/plugins/security-sensitive-files.mjs

@@ -1,4 +1,5 @@
-const SECURITY_SENSITIVE = /(^|\/)(auth|crypto|security|secrets?|payments?|billing|middleware)(\/|\.)|\.env(\.|$)|(^|\/)server\.ts$/i;
+const SECURITY_SENSITIVE =
+  /(^|\/)(auth|crypto|security|secrets?|payments?|billing|middleware)(\/|\.)|\.env(\.|$)|(^|\/)server\.ts$/i;
 
 export default {
   check: async (_rootPath, files) => {

package/docs/examples/swarm-coordination.md

@@ -0,0 +1,109 @@
+# Swarm Coordination Workflow
+
+Use this recipe when two or more agents, worktrees, or developers are changing
+the same repo. The goal is not to prevent parallel work; it is to make overlap,
+claim contention, and merge order visible before code lands.
+
+## Personas
+
+- Platform lead: wants low merge conflict rate and clear ownership when several
+  agents are active.
+- Product engineer: wants to keep moving without reading every sibling branch.
+- Release owner: wants a merge order and proof that high-risk overlaps were
+  reviewed before sign-off.
+
+## Start of Work
+
+Run this before the first edit in each worktree:
+
+```bash
+projscan start --intent "show coordination status for parallel agents" --format json
+projscan coordinate --format json
+projscan claim list --format json
+```
+
+If the work has a known file, claim it with a short lease:
+
+```bash
+projscan claim add src/core/start.ts --agent api-agent --ttl 2700 --format json
+```
+
+Treat a claim conflict as a routing signal. Either choose another task, split
+the file, or ask the owner to release the claim.
+
+## During Work
+
+Use the dedicated coordination tools for specific questions:
+
+```bash
+projscan collisions --format json
+projscan merge-risk --format json
+projscan coordinate --format json
+```
+
+Read the outputs this way:
+
+| Tool | Question answered | Action |
+| --- | --- | --- |
+| `collisions` | Which worktrees touch the same files or dependent files? | Move one branch first, split work, or ask for review. |
+| `claim list` | Who says they own a file, directory, or symbol right now? | Avoid edits under active leases unless agreed. |
+| `merge-risk` | Which branch should merge first? | Integrate the least-entangled branch before larger branches. |
+| `coordinate` | Is the current swarm clear, cautious, or conflicted? | Use this as the one-line status in handoffs. |
+| `agent-brief` | What should the next agent know? | Include coordination hints in the next-agent packet. |
+
+For MCP clients that support long-running notifications, use the watch tool:
+
+```text
+projscan_coordinate_watch { "action": "start" }
+projscan_coordinate_watch { "action": "list" }
+projscan_coordinate_watch { "action": "stop" }
+```
+
+For CLI users, `coordinate` also supports polling:
+
+```bash
+projscan coordinate --watch --interval 5 --format json
+```
+
+The watch loop should be treated as advisory evidence. A changed notification
+or emitted watch row means rerun `projscan coordinate` before editing or merging.
+
+## Before Handoff
+
+Capture a compact handoff with coordination evidence:
+
+```bash
+projscan agent-brief --intent "handoff current parallel-agent work" --format json
+projscan preflight --mode before_commit --format json
+projscan coordinate --format json
+```
+
+Handoff text should include:
+
+- active claims you hold
+- collision count and readiness verdict
+- merge-risk order when multiple worktrees exist
+- exact proof commands already run
+- claim release command if the next agent owns the follow-up
+
+## Before Merge
+
+```bash
+projscan preflight --mode before_merge --format json
+projscan merge-risk --format json
+projscan coordinate --format json
+```
+
+Merge only when the coordination verdict is `clear` or when the release owner
+has reviewed the listed conflicts. If the verdict is `conflicted`, resolve or
+split the overlap before merging.
+
+## Evidence Gaps To Track
+
+These are the next hardening targets for real swarm usage:
+
+- transitive collision recall: prove dependent-file conflicts are caught, not
+  only same-file conflicts
+- live watch adoption: prove agents notice and act on coordination changes
+- preflight and agent-brief integration: prove the same coordination facts show
+  up where agents already look before editing or handing off

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "4.3.1",
+  "version": "4.5.0",
   "description": "Agent-first code intelligence. MCP server (2025-03-26) with 11 AST adapters covering 12 named languages: JavaScript, TypeScript, Python, Go, Java, Ruby, Rust, PHP, C#, Kotlin, Swift, and C++; repo understanding maps (projscan_understand), stable v3 semantic graph (projscan_semantic_graph), dataflow risk engine with bridge-helper detection (projscan_dataflow), code graph, file + per-function AST cyclomatic complexity, per-function fan-in + fan-out, coupling + cycle detection, structural PR diff with HTML reporter, coverage report with HTML reporter, intent-grounded one-call PR review (projscan_review with optional `intent` arg, new taint flows, contract changes, and newDataflowRisks) and long-running PR-watch mode with structured per-bucket deltas (projscan_review_watch), first-60-seconds workflow orientation (projscan_start), agent workplans (projscan_workplan), bug-hunt queues (projscan_bug_hunt), product-line planning (projscan_release_train), evidence packs (projscan_evidence_pack), regression planning (projscan_regression_plan), agent briefs (projscan_agent_brief), quality scorecards (projscan_quality_scorecard), and preflight with supply-chain IOC evidence, rule-driven fix suggestions + mechanical apply layer with rollback (projscan_apply_fix, projscan_fix_suggest, projscan_explain_issue), source-to-sink taint analysis (projscan_taint) with truncation reporting, transitive blast-radius analysis with cross-repo mode (projscan_impact for files and symbols), cross-repo workspace registration + intelligence (projscan_workspace_graph), per-function semantic search chunks (sub-file embeddings), per-rule confidence + severity drift + cost-summary analytics with live streaming (projscan_cost_summary), stable local analyzer + reporter plugin API (projscan_plugin, CLI --reporter, opt-in via PROJSCAN_PLUGINS_PREVIEW=1), monorepo workspace awareness with cross-package import policy + per-package dependencies / outdated / audit, BM25 + optional semantic search, cursor pagination, progress notifications, context-budgeted output, and a stable-surface CI guard. CLI on the side.",
   "type": "module",
   "main": "./dist/index.js",
@@ -21,6 +21,8 @@
     "docs/demos/projscan-mission-control.tape",
     "docs/demos/projscan-mission-proof.tape",
     "docs/plugin.schema.json",
+    "docs/examples/adoption-workflows.md",
+    "docs/examples/swarm-coordination.md",
     "docs/projscan-mission-control.png",
     "docs/projscan-mission-control.gif",
     "docs/projscan-proof-router.png",
@@ -42,8 +44,10 @@
   "scripts": {
     "build": "tsc && node scripts/copy-wasm.mjs && node scripts/generate-tool-manifest.mjs",
     "dev": "tsc --watch",
-    "test": "vitest run --test-timeout 60000 --hook-timeout 60000 --maxWorkers 4",
-    "test:watch": "vitest --test-timeout 60000 --hook-timeout 60000",
+    "typecheck": "tsc --noEmit",
+    "typecheck:public-types": "tsc -p tsconfig.public-types.json",
+    "test": "vitest run --exclude '.worktrees/**' --test-timeout 60000 --hook-timeout 60000 --maxWorkers 4",
+    "test:watch": "vitest --exclude '.worktrees/**' --test-timeout 60000 --hook-timeout 60000",
     "lint": "eslint src/",
     "format": "prettier --write .",
     "bench": "node scripts/bench.mjs",
@@ -58,7 +62,7 @@
     "sbom:generate": "node scripts/generate-sbom.mjs",
     "prepare": "npm run build",
     "check:graph-corpus": "node scripts/check-graph-corpus.mjs",
-    "test:trust-smoke": "vitest run tests/cli/privacyCheck.test.ts tests/cli/start.test.ts tests/cli/preflight.test.ts tests/mcp/start.test.ts tests/mcp/preflight.test.ts tests/mcp/fileChangedNotifications.test.ts tests/core/repositoryScanner.gitignore.test.ts tests/core/issueEngine.trustConfig.test.ts tests/utils/changedFiles.test.ts tests/core/auditRunner.offline.test.ts tests/core/upgradePreview.checkRegistry.test.ts tests/core/telemetry.test.ts tests/analyzers/securityCheck.test.ts --test-timeout 60000 --hook-timeout 60000"
+    "test:trust-smoke": "vitest run --exclude '.worktrees/**' tests/cli/privacyCheck.test.ts tests/cli/start.test.ts tests/cli/preflight.test.ts tests/mcp/start.test.ts tests/mcp/preflight.test.ts tests/mcp/fileChangedNotifications.test.ts tests/core/repositoryScanner.gitignore.test.ts tests/core/issueEngine.trustConfig.test.ts tests/utils/changedFiles.test.ts tests/core/auditRunner.offline.test.ts tests/core/upgradePreview.checkRegistry.test.ts tests/core/telemetry.test.ts tests/analyzers/securityCheck.test.ts --test-timeout 60000 --hook-timeout 60000"
   },
   "keywords": [
     "cli",
@@ -118,14 +122,17 @@
     "@eslint/js": "^10.0.1",
     "@types/node": "^22.0.0",
     "@xenova/transformers": "^2.17.0",
+    "agentflight": "^0.4.1",
+    "agentloopkit": "^0.33.0",
     "eslint": "^10.0.3",
+    "prettier": "^3.8.4",
     "tree-sitter-cli": "^0.26.8",
     "tree-sitter-cpp": "^0.23.4",
     "tree-sitter-kotlin": "^0.3.8",
     "tree-sitter-swift": "^0.7.1",
     "typescript": "^5.6.0",
     "typescript-eslint": "^8.57.0",
-    "vite": "^6.4.2",
+    "vite": "^8.0.16",
     "vitest": "^4.1.8"
   },
   "overrides": {