projscan 4.2.0 → 4.3.1

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

@@ -422,34 +422,34 @@
       <section class="hero" aria-label="projscan Mission Control">
         <div class="intro">
           <div>
-            <p class="eyebrow">Developer-life upgrade</p>
-            <h1>Tell projscan what you are doing.</h1>
+            <p class="eyebrow">Mission Outcome Loop</p>
+            <h1>Resume from real proof.</h1>
             <p class="lead">
-              projscan routes a developer goal to the next safe command, the
-              MCP call an agent can run, and the proof that makes a handoff
-              reviewable.
+              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>
               <span class="pill">Local-first</span>
               <span class="pill">MCP-ready</span>
-              <span class="pill">Copyable handoff</span>
-              <span class="pill">Review gate</span>
+              <span class="pill">Outcome resume</span>
+              <span class="pill">Proof report</span>
             </div>
           </div>
 
           <div class="metric-row" aria-label="Release candidate signals">
             <div class="metric">
-              <strong>1 call</strong>
-              <span>intent to workflow</span>
+              <strong>1 bundle</strong>
+              <span>mission plus proof</span>
             </div>
             <div class="metric">
-              <strong>1 JSON</strong>
-              <span>next MCP call</span>
+              <strong>45</strong>
+              <span>MCP tools</span>
             </div>
             <div class="metric">
-              <strong>0</strong>
-              <span>source uploads</span>
+              <strong>11 / 12</strong>
+              <span>AST adapters / languages</span>
             </div>
           </div>
         </div>
@@ -459,83 +459,68 @@
             <span class="dot red"></span>
             <span class="dot amber"></span>
             <span class="dot green"></span>
-            <span class="terminal-title">projscan start shortcuts</span>
+            <span class="terminal-title">projscan start --mission</span>
           </div>
           <div class="terminal-body">
             <span class="line"
               ><span class="prompt">$</span>
               <span class="cmd"
-                >projscan start --intent "what breaks if I rename the auth
-                token loader"</span
+                >projscan start --mission .projscan/mission</span
               ></span
             >
             <span class="line dim">ProjScan Mission Control</span>
-            <span class="line">Intent: what breaks if I rename the auth token loader</span>
-            <span class="line">Status: <span class="warn">needs_attention</span></span>
+            <span class="line">Mission: .projscan/mission</span>
+            <span class="line">Status: <span class="success">passed</span></span>
             <span class="line"
-              >Route:
-              <span class="notice">Impact analysis via projscan_search</span></span
+              >Outcome:
+              <span class="notice">proof passed after 3 commands</span></span
             >
             <span class="line dim"
-              >confidence: high; matched: breaks, rename</span
+              >read proof-logs/summary.json and status.jsonl</span
             >
 
             <div class="term-section">
-              <span class="line term-heading">Run Cursor</span>
+              <span class="line term-heading">What Changed</span>
               <span class="line"
-                >command: projscan search "auth token loader" --format
-                json</span
+                >- Mission proof passed after 3 command(s).</span
               >
               <span class="line"
-                >MCP call: projscan_search {"query":"auth token loader"}</span
+                >- 1 reviewer decision recorded.</span
               >
-              <span class="line">unlocks: symbol input, file input</span>
+              <span class="line">- 0 failed gates remain.</span>
             </div>
 
             <div class="term-section">
-              <span class="line term-heading">Copyable Shortcuts</span>
+              <span class="line term-heading">What Remains</span>
               <span class="line success"
-                >projscan start --shortcuts --intent "..."</span
+                >Run ./review.sh and choose a reviewer reply.</span
               >
               <span class="line success"
-                >projscan start --next-command --intent "..."</span
-              >
-              <span class="line success"
-                >projscan start --next-tool-call --intent "..."</span
-              >
-              <span class="line success"
-                >projscan start --task-card --intent "..."</span
+                >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-script --intent "..."</span
+                >projscan start --mission .projscan/mission</span
               >
               <span class="line success"
-                >projscan start --review-gate --intent "..."</span
+                >projscan mission-proof --mission .projscan/mission</span
               >
               <span class="line success"
-                >projscan start --save-mission .projscan/mission --intent
-                "..."</span
+                >projscan mission-proof --baseline manual-runs.json</span
               >
-              <span class="line dim">writes task card, review gate, mission.sh</span>
+              <span class="line dim">all source stays local</span>
             </div>
 
             <div class="term-section">
-              <span class="line term-heading">Ready Proof</span>
+              <span class="line term-heading">Proof Evidence</span>
               <span class="line success"
-                >- projscan preflight --mode before_edit --format json</span
+                >proof-logs/summary.json: passed</span
               >
               <span class="line success"
-                >- projscan understand --view verify --format json</span
-              >
-            </div>
-
-            <div class="term-section">
-              <span class="line term-heading">Done When</span>
-              <span class="line"
-                >- Search returns an exact symbol or file path</span
-              >
-              <span class="line"
-                >- Impact is reviewed before code edits</span
+                >proof-logs/status.jsonl: 3 rows</span
               >
             </div>
 
@@ -543,8 +528,8 @@
               <span class="line term-heading">Review Gate</span>
               <span class="line">capture: git status --short</span>
               <span class="line">capture: git diff --stat</span>
-              <span class="line success">reply: Approved, one bounded slice</span>
-              <span class="line warn">stop before another slice or release</span>
+              <span class="line success">reply: review version candidate</span>
+              <span class="line warn">do not publish until approved</span>
             </div>
           </div>
         </section>
@@ -553,7 +538,7 @@
       <section class="grid" aria-label="New developer workflows">
         <article class="card">
           <span class="label green">Goal routing</span>
-          <h2>Ask in human language.</h2>
+          <h2>Ask in plain language.</h2>
           <p>
             Route privacy, merge readiness, refactor risk, local setup,
             ownership, dependency, release, and handoff questions to the right
@@ -561,21 +546,21 @@
           </p>
         </article>
         <article class="card">
-          <span class="label blue">Repo context</span>
-          <h2>Start from cited evidence.</h2>
+          <span class="label blue">Outcome resume</span>
+          <h2>Start from saved proof.</h2>
           <p>
-            Repo maps now include read-first files, package contracts, runtime
-            flows, public exports, proof tiers, setup commands, and unknowns
-            that need human input.
+            <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">Review proof</span>
-          <h2>Make PRs easier to approve.</h2>
+          <span class="label amber">Proof report</span>
+          <h2>Measure the saved work.</h2>
           <p>
-            Mission Control carries the original intent into preflight,
-            verification, session memory, evidence packs, and reviewer-ready
-            next commands.
+            <code>projscan mission-proof</code> reports proof completion,
+            reviewer approvals, reruns, failed gates, time saved, and local
+            risk avoided.
           </p>
         </article>
       </section>
@@ -583,13 +568,13 @@
       <section class="proof" id="proof" aria-label="Proof and dependency view">
         <div class="proof-header">
           <div>
-            <p class="eyebrow">Intent, graph, and handoff intelligence</p>
-            <h2>Copy the next move.</h2>
+            <p class="eyebrow">Proof, review, and adoption evidence</p>
+            <h2>Close the loop.</h2>
           </div>
           <p>
-            Developers and agents can list the shortcut menu, pull the next
-            shell command, fetch the MCP call, or copy the checklist and
-            Markdown runbook without reading the full report.
+            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>
 
@@ -599,33 +584,32 @@
               <span class="dot red"></span>
               <span class="dot amber"></span>
               <span class="dot green"></span>
-              <span class="terminal-title">projscan start --next-tool-call</span>
+              <span class="terminal-title">projscan mission-proof</span>
             </div>
             <div class="terminal-body">
               <span class="line"
                 ><span class="prompt">$</span>
                 <span class="cmd"
-                  >projscan start --next-tool-call --intent "what breaks if I
-                  rename the auth token loader"</span
+                  >projscan mission-proof --mission .projscan/mission --format
+                  json</span
                 ></span
               >
-              <span class="line dim">Current cursor as MCP JSON</span>
+              <span class="line dim">Local proof summary</span>
               <span class="line">&nbsp;</span>
-              <span class="line term-heading">{"tool":"projscan_search",</span>
+              <span class="line term-heading">{"passed":1,"failed":0,</span>
               <span class="line success"
-                >&nbsp;"args":{"query":"auth token loader"}}</span
+                >&nbsp;"reruns":0,"reviewerApprovals":1}</span
               >
               <span class="line">&nbsp;</span>
-              <span class="line term-heading">Checklist handoff</span>
+              <span class="line term-heading">Risk avoided</span>
               <span class="line success"
-                >- [ready] run_current ready-1</span
+                >- proof gate passed before release</span
               >
               <span class="line success"
-                >- [blocked] resolve_input input-1</span
+                >- version review is safe to request</span
               >
-              <span class="line success">- [ready] run_proof proof-2</span>
               <span class="line notice"
-                >Review gate: capture status, diff, then wait.</span
+                >Next: projscan start --mission .projscan/mission</span
               >
             </div>
           </section>
@@ -634,33 +618,33 @@
             <div class="signal">
               <span class="tag green">Verify</span>
               <span>
-                <strong>Proof commands</strong>
-                <code>--proof-commands</code> returns the remaining
-                verification commands, one per line.
+                <strong>Outcome resume</strong>
+                <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 call shortcut</strong>
-                <code>--next-tool-call</code> returns the cursor tool and args
-                as compact JSON.
+                <strong>MCP start input</strong>
+                <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>Checklist shortcut</strong>
-                <code>--checklist</code> returns current, blocked, follow-up,
-                proof, and done rows.
+                <strong>Proof summary</strong>
+                <code>mission-proof</code> reports completion, reruns, failed
+                gates, and approvals.
               </span>
             </div>
             <div class="signal">
               <span class="tag red">Gate</span>
               <span>
-                <strong>Review gate</strong>
-                <code>--review-gate</code> returns the stop checklist before
-                another slice, release, publish, or deploy.
+                <strong>Version review</strong>
+                Outcome data says whether to request review or keep fixing
+                failed proof.
               </span>
             </div>
           </div>

package/docs/demos/projscan-mission-control.tape

@@ -0,0 +1,13 @@
+Output docs/projscan-mission-control.gif
+
+Set Shell "bash"
+Set FontSize 16
+Set Width 1200
+Set Height 720
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 35ms
+Set Padding 16
+
+Type "projscan start --shortcuts --intent 'is it safe to commit this change?'"
+Enter
+Sleep 12s

package/docs/demos/projscan-mission-proof.tape

@@ -0,0 +1,25 @@
+Output docs/projscan-mission-proof.gif
+
+Set Shell "bash"
+Set FontSize 16
+Set Width 1200
+Set Height 720
+Set Theme "Catppuccin Mocha"
+Set TypingSpeed 35ms
+Set Padding 16
+
+Type "rm -rf .projscan/vhs-mission"
+Enter
+Sleep 500ms
+
+Type "projscan start --save-mission .projscan/vhs-mission --intent 'is it safe to commit this change?'"
+Enter
+Sleep 10s
+
+Type "projscan mission-proof --mission .projscan/vhs-mission --format markdown | sed -n '1,38p'"
+Enter
+Sleep 8s
+
+Type "projscan start --mission .projscan/vhs-mission --handoff-prompt | sed -n '1,8p'"
+Enter
+Sleep 16s

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "projscan",
   "mcpName": "io.github.abhiyoheswaran1/projscan",
-  "version": "4.2.0",
-  "description": "Agent-first code intelligence. MCP server (2025-03-26) with AST parsing for 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.",
+  "version": "4.3.1",
+  "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",
   "types": "./dist/index.d.ts",
@@ -18,11 +18,16 @@
     "docs/PLUGIN-GALLERY.md",
     "docs/ROADMAP.md",
     "docs/demos/projscan-4-1-demo.html",
+    "docs/demos/projscan-mission-control.tape",
+    "docs/demos/projscan-mission-proof.tape",
     "docs/plugin.schema.json",
     "docs/projscan-mission-control.png",
+    "docs/projscan-mission-control.gif",
     "docs/projscan-proof-router.png",
+    "docs/projscan-mission-proof.gif",
     "docs/examples/plugins",
     "scripts/capture-readme-assets.mjs",
+    "scripts/capture-vhs-demos.mjs",
     "public/brand/baseframe-labs",
     "public/.well-known/security.txt",
     "CONTRIBUTING.md",
@@ -44,6 +49,8 @@
     "bench": "node scripts/bench.mjs",
     "bench:references": "node scripts/bench-references.mjs",
     "docs:screenshots": "node scripts/capture-readme-assets.mjs",
+    "docs:demos": "npm run build && node scripts/capture-vhs-demos.mjs",
+    "docs:assets": "npm run docs:screenshots && npm run docs:demos",
     "smoke:packed-install": "node scripts/packed-install-smoke.mjs",
     "check:stability": "node scripts/check-stability.mjs",
     "release:check": "node scripts/release-check.mjs",

package/scripts/capture-vhs-demos.mjs

@@ -0,0 +1,80 @@
+import { chmodSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const cliPath = path.join(repoRoot, 'dist', 'cli', 'index.js');
+const vhsBinDir = path.join(repoRoot, '.projscan', 'vhs-bin');
+const vhsShimPath = path.join(vhsBinDir, 'projscan');
+const vhsMissionDir = path.join(repoRoot, '.projscan', 'vhs-mission');
+
+const tapes = [
+  {
+    name: 'Mission Control terminal demo',
+    tape: path.join(repoRoot, 'docs', 'demos', 'projscan-mission-control.tape'),
+    output: path.join(repoRoot, 'docs', 'projscan-mission-control.gif'),
+  },
+  {
+    name: 'Mission Proof terminal demo',
+    tape: path.join(repoRoot, 'docs', 'demos', 'projscan-mission-proof.tape'),
+    output: path.join(repoRoot, 'docs', 'projscan-mission-proof.gif'),
+  },
+];
+
+const quoteForShell = (value) => `'${value.replaceAll("'", "'\"'\"'")}'`;
+
+const fail = (message, status = 1) => {
+  console.error(message);
+  process.exit(status);
+};
+
+if (!existsSync(cliPath)) {
+  fail('Missing dist/cli/index.js. Run `npm run build` before capturing VHS demos.');
+}
+
+const vhsVersion = spawnSync('vhs', ['--version'], { cwd: repoRoot, encoding: 'utf8' });
+if (vhsVersion.status !== 0) {
+  fail('Missing `vhs`. Install it with `brew install vhs`, then run `npm run docs:demos`.');
+}
+
+for (const tape of tapes) {
+  if (!existsSync(tape.tape)) {
+    fail(`Missing VHS tape: ${path.relative(repoRoot, tape.tape)}`);
+  }
+}
+
+mkdirSync(vhsBinDir, { recursive: true });
+writeFileSync(vhsShimPath, `#!/usr/bin/env sh\nexec node ${quoteForShell(cliPath)} "$@"\n`);
+chmodSync(vhsShimPath, 0o755);
+
+const env = {
+  ...process.env,
+  PATH: `${vhsBinDir}${path.delimiter}${process.env.PATH ?? ''}`,
+};
+
+try {
+  rmSync(vhsMissionDir, { recursive: true, force: true });
+
+  for (const tape of tapes) {
+    console.log(`Capturing ${tape.name} -> ${path.relative(repoRoot, tape.output)}`);
+    const result = spawnSync('vhs', [path.relative(repoRoot, tape.tape)], {
+      cwd: repoRoot,
+      env,
+      stdio: 'inherit',
+    });
+
+    if (result.status !== 0) {
+      fail(`VHS capture failed for ${path.relative(repoRoot, tape.tape)}`, result.status ?? 1);
+    }
+
+    if (!existsSync(tape.output)) {
+      fail(`VHS did not write expected output: ${path.relative(repoRoot, tape.output)}`);
+    }
+  }
+} finally {
+  rmSync(vhsMissionDir, { recursive: true, force: true });
+  rmSync(vhsBinDir, { recursive: true, force: true });
+}
+
+console.log('VHS demos captured.');