projscan 1.3.0 → 1.5.0

package/README.md

@@ -20,7 +20,7 @@
 
 AI coding agents are becoming the primary interface to code. Today, when you ask your agent *"which files implement auth?"* or *"what breaks if I bump React from 18 to 19?"* - it either guesses from names, or it shells out to grep and reads raw output not built for it.
 
-**projscan is the first code-intelligence tool built for agents, not for humans.** Your agent gets a fast, AST-accurate, context-budget-aware view of your codebase through 20 structured MCP tools. It can query the import graph, find symbol definitions, preview upgrades, rank hotspots, diff structural changes between refs, surface coupling/cycle hotspots, get a one-call PR review, request structured fix-action prompts for any open issue, and ask "what breaks if I change this?" via transitive blast-radius analysis - without loading the file tree into its context.
+**projscan is the first code-intelligence tool built for agents, not for humans.** Your agent gets a fast, AST-accurate, context-budget-aware view of your codebase through 22 structured MCP tools. It can query the import graph, find symbol definitions, preview upgrades, rank hotspots, diff structural changes between refs, surface coupling/cycle hotspots, get a one-call PR review, request structured fix-action prompts for any open issue, ask "what breaks if I change this?" via transitive blast-radius analysis, share a durable session across multiple agent invocations, and learn from how you use it — quieting accumulated noise on this specific repo over time without ever phoning home.
 
 Humans get the same thing through the CLI.
 
@@ -231,12 +231,12 @@ Cache version bumped 2 → 3 in 0.11 (CC stored per file). Existing v2 caches ar
 
 ## Performance
 
-Reference numbers from `npm run bench` on an Apple M3 Pro running Node 25 (cold / warm cache, milliseconds). These are the 1.0 reference numbers:
+Reference numbers from `npm run bench` on an Apple M3 Pro running Node 25 (cold / warm cache, milliseconds), refreshed for 1.5.0:
 
 | Repo | Files | analyze | doctor | hotspots | coupling | search |
 |------|-------|---------|--------|----------|----------|--------|
-| projscan itself | ~135 | 612 / 463 | 557 / 509 | 673 / 507 | 364 / 173 | 439 / 258 |
-| Synthetic medium | 500 | 278 / 268 | 274 / 260 | 300 / 297 | 217 / 174 | 238 / 193 |
+| projscan itself | ~120 | 650 / 576 | 659 / 574 | 794 / 622 | 405 / 186 | 485 / 277 |
+| Synthetic medium | 500 | 284 / 257 | 277 / 255 | 300 / 278 | 224 / 177 | 239 / 196 |
 
 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`.
 
@@ -515,25 +515,104 @@ Coverage is also automatically joined into `projscan hotspots` when one of those
 
 **This is the primary way to use projscan.** `projscan mcp` starts an [MCP](https://modelcontextprotocol.io) server over stdio so AI coding agents can query your codebase with real structural accuracy - not regex, not grep.
 
+<img src="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">
+
+Two questions an agent asks; structural answers in milliseconds. *"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.
+
 ### Claude Code
 
+One-liner — adds projscan as an MCP server in the current project:
+
 ```bash
-claude mcp add projscan -- npx projscan mcp
+claude mcp add projscan -- npx -y projscan mcp
+```
+
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):
+
+```json
+{
+  "mcpServers": {
+    "projscan": {
+      "command": "npx",
+      "args": ["-y", "projscan", "mcp"]
+    }
+  }
+}
 ```
 
-### Cursor / Windsurf / any MCP client
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
 
 ```json
 {
   "mcpServers": {
     "projscan": {
       "command": "npx",
-      "args": ["projscan", "mcp"]
+      "args": ["-y", "projscan", "mcp"]
     }
   }
 }
 ```
 
+### Cline (VS Code extension)
+
+In Cline's MCP settings panel (or the underlying `cline_mcp_settings.json`):
+
+```json
+{
+  "mcpServers": {
+    "projscan": {
+      "command": "npx",
+      "args": ["-y", "projscan", "mcp"]
+    }
+  }
+}
+```
+
+### Continue.dev
+
+Add to `~/.continue/config.yaml`:
+
+```yaml
+mcpServers:
+  - name: projscan
+    command: npx
+    args:
+      - -y
+      - projscan
+      - mcp
+```
+
+### Zed
+
+Add to `~/.config/zed/settings.json` under `context_servers`:
+
+```json
+{
+  "context_servers": {
+    "projscan": {
+      "command": {
+        "path": "npx",
+        "args": ["-y", "projscan", "mcp"]
+      }
+    }
+  }
+}
+```
+
+### Any other MCP-aware client
+
+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`:
+
+```bash
+npx -y projscan mcp --watch
+```
+
+Capability is advertised under `experimental.fileChanged` on `initialize` so clients can detect support.
+
 ### What agents can ask
 
 - *"Who imports `src/auth/jwt.ts`?"* → `projscan_graph { file, direction: "importers" }`
@@ -543,7 +622,7 @@ claude mcp add projscan -- npx projscan mcp
 - *"What breaks if I bump chalk to 6?"* → `projscan_upgrade { package: "chalk" }`
 - *"Where should I refactor first?"* → `projscan_hotspots`
 
-### The 20 MCP tools
+### The 22 MCP tools
 
 **Structural (0.6.0 / 0.11 / 0.13 / 0.14 / 0.15 - agent-native):**
 - **`projscan_graph`** - query the AST-based code graph. Directions: `imports`, `exports`, `importers`, `symbol_defs`, `package_importers`. Millisecond responses on a warm cache.
@@ -573,6 +652,12 @@ claude mcp add projscan -- npx projscan mcp
 **Workspace (0.11):**
 - `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.
 
+**Session (1.4):**
+- **`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. Lets multiple agents in the same project see "what's been touched here" without re-running git.
+
+**Memory (1.5):**
+- **`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.
+
 ### Context-window budgeting
 
 **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.
@@ -616,9 +701,13 @@ All opt-in - default behavior is unchanged.
 
 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.
 
-### Prompts (2, parameterized with live project data)
+### Prompts (6, parameterized with live project data)
 - `prioritize_refactoring` - ranked plan grounded in current hotspots
 - `investigate_file` - senior-engineer brief for a specific file
+- **`refactor_hotspot`** *(1.5)* - step-by-step refactor plan for one hotspot file
+- **`triage_doctor_issues`** *(1.5)* - critical / important / backlog ordering of open issues
+- **`review_this_pr`** *(1.5)* - PR-comment-ready review primed with the structural diff and verdict
+- **`safely_rename_symbol`** *(1.5)* - ordered rename + verification checklist via `projscan_impact` blast radius
 
 ### Resources (3, readable on demand)
 - `projscan://health` · `projscan://hotspots` · `projscan://structure`

package/dist/cli/commands/doctor.js

@@ -10,6 +10,7 @@ import { reportHealthJson } from '../../reporters/jsonReporter.js';
 import { reportHealthMarkdown } from '../../reporters/markdownReporter.js';
 import { reportHealthSarif } from '../../reporters/sarifReporter.js';
 import { reportHealthHtml } from '../../reporters/htmlReporter.js';
+import { findStableRules, loadMemory } from '../../core/memory.js';
 export function registerDoctor() {
     program
         .command('doctor')
@@ -51,8 +52,23 @@ export function registerDoctor() {
                 case 'html':
                     reportHealthHtml(issues);
                     break;
-                default:
-                    reportHealth(issues, scan.scanDurationMs);
+                default: {
+                    // 1.5+ — surface a Project Memory tip when stable rules
+                    // have accumulated. Best-effort: a memory load failure
+                    // never blocks the doctor output.
+                    let stableRuleCount = 0;
+                    try {
+                        const memory = await loadMemory(rootPath);
+                        stableRuleCount = findStableRules(memory).length;
+                    }
+                    catch {
+                        // best-effort
+                    }
+                    reportHealth(issues, {
+                        scanTimeMs: scan.scanDurationMs,
+                        stableRuleCount,
+                    });
+                }
             }
         }
         catch (error) {

package/dist/cli/commands/doctor.js.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/cli/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/explain.js

@@ -31,6 +31,7 @@ export function registerExplain() {
         catch (error) {
             if (error.code === 'ENOENT') {
                 console.error(chalk.red(`File not found: ${filePath}`));
+                console.error(chalk.dim(`  Tip: paths are repo-relative. Run \`projscan structure\` to see the file tree.`));
             }
             else {
                 console.error(chalk.red(error instanceof Error ? error.message : String(error)));

package/dist/cli/commands/explain.js.map

@@ -1 +1 @@
-{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAEhF,MAAM,UAAU,eAAe;IAC7B,OAAO;SACJ,OAAO,CAAC,gBAAgB,CAAC;SACzB,WAAW,CAAC,yDAAyD,CAAC;SACtE,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,EAAE;QACjC,aAAa,EAAE,CAAC;QAChB,kBAAkB,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YACzD,MAAM,WAAW,GAAG,WAAW,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YAEvD,QAAQ,MAAM,EAAE,CAAC;gBACf,KAAK,MAAM;oBACT,qBAAqB,CAAC,WAAW,CAAC,CAAC;oBACnC,MAAM;gBACR,KAAK,UAAU;oBACb,yBAAyB,CAAC,WAAW,CAAC,CAAC;oBACvC,MAAM;gBACR;oBACE,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC,CAAC;YAC1D,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACnF,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}
+{"version":3,"file":"explain.js","sourceRoot":"","sources":["../../../src/cli/commands/explain.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,OAAO,CAAC;AAC1B,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAElC,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,aAAa,EAAE,kBAAkB,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACnG,OAAO,EAAE,iBAAiB,EAAE,MAAM,oCAAoC,CAAC;AACvE,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EAAE,yBAAyB,EAAE,MAAM,qCAAqC,CAAC;AAEhF,MAAM,UAAU,eAAe;IAC7B,OAAO;SACJ,OAAO,CAAC,gBAAgB,CAAC;SACzB,WAAW,CAAC,yDAAyD,CAAC;SACtE,MAAM,CAAC,KAAK,EAAE,QAAgB,EAAE,EAAE;QACjC,aAAa,EAAE,CAAC;QAChB,kBAAkB,EAAE,CAAC;QACrB,MAAM,MAAM,GAAG,SAAS,EAAE,CAAC;QAC3B,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QAE5C,IAAI,CAAC;YACH,MAAM,OAAO,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YACzD,MAAM,WAAW,GAAG,WAAW,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;YAEvD,QAAQ,MAAM,EAAE,CAAC;gBACf,KAAK,MAAM;oBACT,qBAAqB,CAAC,WAAW,CAAC,CAAC;oBACnC,MAAM;gBACR,KAAK,UAAU;oBACb,yBAAyB,CAAC,WAAW,CAAC,CAAC;oBACvC,MAAM;gBACR;oBACE,iBAAiB,CAAC,WAAW,CAAC,CAAC;YACnC,CAAC;QACH,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;gBACvD,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,mBAAmB,QAAQ,EAAE,CAAC,CAAC,CAAC;gBACxD,OAAO,CAAC,KAAK,CACX,KAAK,CAAC,GAAG,CAAC,kFAAkF,CAAC,CAC9F,CAAC;YACJ,CAAC;iBAAM,CAAC;gBACN,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,CAAC,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;YACnF,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAClB,CAAC;IACH,CAAC,CAAC,CAAC;AACP,CAAC"}

package/dist/cli/commands/memory.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `projscan memory` — inspect or prune the local Project Memory store
+ * that learns which analyzer rules this repo has been carrying across
+ * many runs.
+ *
+ *   projscan memory                  — aggregate summary (default)
+ *   projscan memory stable           — long-running rules + .projscanrc snippet
+ *   projscan memory runs             — every tracked rule with full history
+ *   projscan memory forget <rule>    — drop a single rule's history
+ */
+export declare function registerMemory(): void;

package/dist/cli/commands/memory.js

@@ -0,0 +1,175 @@
+import chalk from 'chalk';
+import { program, getRootPath, getFormat, setupLogLevel, maybeCompactBanner } from '../_shared.js';
+import { findStableRules, forgetRule, loadMemory, saveMemory, } from '../../core/memory.js';
+/**
+ * `projscan memory` — inspect or prune the local Project Memory store
+ * that learns which analyzer rules this repo has been carrying across
+ * many runs.
+ *
+ *   projscan memory                  — aggregate summary (default)
+ *   projscan memory stable           — long-running rules + .projscanrc snippet
+ *   projscan memory runs             — every tracked rule with full history
+ *   projscan memory forget <rule>    — drop a single rule's history
+ */
+export function registerMemory() {
+    const memory = program
+        .command('memory')
+        .description('Inspect or prune the local Project Memory (1.5+)')
+        .action(async () => {
+        await runSummary();
+    });
+    memory
+        .command('stable')
+        .description('Show rules that have been surfacing across enough runs to count as accepted')
+        .action(async () => {
+        await runStable();
+    });
+    memory
+        .command('runs')
+        .description('Show every tracked rule with its observation history')
+        .action(async () => {
+        await runRuns();
+    });
+    memory
+        .command('forget <rule>')
+        .description("Drop a single rule's history from memory")
+        .action(async (rule) => {
+        await runForget(rule);
+    });
+}
+async function runSummary() {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const m = await loadMemory(rootPath);
+        if (format === 'json') {
+            console.log(JSON.stringify(summarize(m), null, 2));
+            return;
+        }
+        printSummary(m);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+async function runStable() {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const m = await loadMemory(rootPath);
+        const stable = findStableRules(m);
+        if (format === 'json') {
+            console.log(JSON.stringify({ totalRuns: m.totalRuns, stable }, null, 2));
+            return;
+        }
+        printStable(m, stable);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+async function runRuns() {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const m = await loadMemory(rootPath);
+        const all = Object.values(m.rules).sort((a, b) => b.runCount - a.runCount);
+        if (format === 'json') {
+            console.log(JSON.stringify({ totalRuns: m.totalRuns, rules: all }, null, 2));
+            return;
+        }
+        printRuns(m, all);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+async function runForget(rule) {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    try {
+        const m = await loadMemory(rootPath);
+        const existed = forgetRule(m, rule);
+        if (existed) {
+            await saveMemory(rootPath, m);
+            console.log(chalk.green(`✓ Dropped "${rule}" from memory.`));
+        }
+        else {
+            console.log(chalk.dim(`No memory entry for "${rule}".`));
+        }
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+function summarize(m) {
+    return {
+        totalRuns: m.totalRuns,
+        rulesTracked: Object.keys(m.rules).length,
+        stableRuleCount: findStableRules(m).length,
+        lastUpdatedAt: m.lastUpdatedAt,
+    };
+}
+function printSummary(m) {
+    const stableCount = findStableRules(m).length;
+    console.log('');
+    console.log(chalk.bold('Project Memory'));
+    console.log(chalk.dim('────────────────────────────────────────'));
+    console.log(`  total runs:    ${m.totalRuns}`);
+    console.log(`  rules tracked: ${Object.keys(m.rules).length}`);
+    console.log(`  stable rules:  ${stableCount > 0 ? chalk.yellow(stableCount) : '0'} ${chalk.dim('(unfixed across many runs)')}`);
+    console.log(`  last updated:  ${m.lastUpdatedAt}`);
+    if (stableCount > 0) {
+        console.log('');
+        console.log(chalk.dim('  Tip: run `projscan memory stable` to see which rules to consider disabling in .projscanrc.'));
+    }
+}
+function printStable(m, stable) {
+    console.log('');
+    console.log(chalk.bold('Stable rules (effectively accepted)'));
+    console.log(chalk.dim('────────────────────────────────────────'));
+    if (stable.length === 0) {
+        console.log(chalk.dim('  No stable rules yet — they appear after a rule has surfaced across'));
+        console.log(chalk.dim('  ≥ 3 runs over ≥ 7 days without ever being fixed.'));
+        return;
+    }
+    for (const r of stable) {
+        console.log(`  ${chalk.yellow('▲')} ${chalk.bold(r.ruleId)}  ${chalk.dim(`(seen in ${r.runCount} runs since ${r.firstSeenAt.slice(0, 10)})`)}`);
+    }
+    console.log('');
+    console.log(chalk.bold('  Suggested .projscanrc.json:'));
+    console.log('');
+    console.log('  ' + JSON.stringify({ disableRules: stable.map((r) => r.ruleId) }, null, 2).split('\n').join('\n  '));
+}
+function printRuns(m, all) {
+    console.log('');
+    console.log(chalk.bold(`Tracked rules (${all.length})`));
+    console.log(chalk.dim('────────────────────────────────────────'));
+    if (all.length === 0) {
+        console.log(chalk.dim('  No rules tracked yet. Memory begins recording on `projscan doctor` runs.'));
+        return;
+    }
+    for (const r of all.slice(0, 30)) {
+        const status = r.suppressedInConfig
+            ? chalk.dim('[suppressed]')
+            : r.fixedCount > 0
+                ? chalk.green(`[fixed ×${r.fixedCount}]`)
+                : chalk.dim('[active]');
+        console.log(`  runs ${String(r.runCount).padStart(3)}  ${status} ${r.ruleId}`);
+    }
+    if (all.length > 30) {
+        console.log(chalk.dim(`  ... and ${all.length - 30} more`));
+    }
+}
+//# sourceMappingURL=memory.js.map

package/dist/cli/commands/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../../src/cli/commands/memory.ts"],"names":[],"mappings":"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"}

package/dist/cli/commands/session.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `projscan session` — inspect the durable cross-invocation session that
+ * the MCP server populates as agents work. Mirrors the `projscan_session`
+ * MCP tool but for terminal use.
+ *
+ * Subcommands:
+ *   projscan session                  — current session summary (default)
+ *   projscan session touched          — list files touched this session
+ *   projscan session events           — chronological event log
+ *   projscan session reset            — discard the current session
+ */
+export declare function registerSession(): void;

package/dist/cli/commands/session.js

@@ -0,0 +1,200 @@
+import chalk from 'chalk';
+import { program, getRootPath, getFormat, setupLogLevel, maybeCompactBanner } from '../_shared.js';
+import { loadSession, resetSession, } from '../../core/session.js';
+/**
+ * `projscan session` — inspect the durable cross-invocation session that
+ * the MCP server populates as agents work. Mirrors the `projscan_session`
+ * MCP tool but for terminal use.
+ *
+ * Subcommands:
+ *   projscan session                  — current session summary (default)
+ *   projscan session touched          — list files touched this session
+ *   projscan session events           — chronological event log
+ *   projscan session reset            — discard the current session
+ */
+export function registerSession() {
+    const session = program
+        .command('session')
+        .description('Inspect or reset the durable cross-invocation session (1.4+)')
+        .action(async () => {
+        await runSummary();
+    });
+    session
+        .command('touched')
+        .description('List files touched this session (sorted by last-touched desc)')
+        .option('--source <source>', 'restrict to tool-result | fs-watch | explicit')
+        .option('--limit <n>', 'show at most N entries', (v) => parseInt(v, 10))
+        .action(async (opts) => {
+        await runTouched(opts);
+    });
+    session
+        .command('events')
+        .description('Show the session event log, newest first')
+        .option('--limit <n>', 'show at most N entries', (v) => parseInt(v, 10))
+        .action(async (opts) => {
+        await runEvents(opts);
+    });
+    session
+        .command('reset')
+        .description('Discard the current session and start a fresh one')
+        .action(async () => {
+        await runReset();
+    });
+}
+async function runSummary() {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const { session: sess, created } = await loadSession(rootPath);
+        if (format === 'json') {
+            console.log(JSON.stringify({ session: sess, created }, null, 2));
+            return;
+        }
+        printSummary(sess, created);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+async function runTouched(opts) {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const { session: sess } = await loadSession(rootPath);
+        const all = Object.values(sess.touchedFiles);
+        const filtered = opts.source ? all.filter((t) => t.source === opts.source) : all;
+        filtered.sort((a, b) => b.lastTouchedAt.localeCompare(a.lastTouchedAt));
+        const limited = typeof opts.limit === 'number' && opts.limit > 0 ? filtered.slice(0, opts.limit) : filtered;
+        if (format === 'json') {
+            console.log(JSON.stringify({ sessionId: sess.id, total: filtered.length, touched: limited }, null, 2));
+            return;
+        }
+        printTouched(sess, limited, filtered.length);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+async function runEvents(opts) {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const { session: sess } = await loadSession(rootPath);
+        const reversed = [...sess.events].reverse();
+        const limited = typeof opts.limit === 'number' && opts.limit > 0 ? reversed.slice(0, opts.limit) : reversed;
+        if (format === 'json') {
+            console.log(JSON.stringify({ sessionId: sess.id, total: reversed.length, events: limited }, null, 2));
+            return;
+        }
+        printEvents(sess, limited, reversed.length);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+async function runReset() {
+    setupLogLevel();
+    maybeCompactBanner();
+    const rootPath = getRootPath();
+    const format = getFormat();
+    try {
+        const fresh = await resetSession(rootPath);
+        if (format === 'json') {
+            console.log(JSON.stringify({ reset: true, session: fresh }, null, 2));
+            return;
+        }
+        console.log(chalk.green('✓ Session reset.'));
+        console.log(`  New session id: ${fresh.id}`);
+        console.log(`  Started at: ${fresh.startedAt}`);
+    }
+    catch (error) {
+        console.error(chalk.red(error instanceof Error ? error.message : String(error)));
+        process.exit(1);
+    }
+}
+function printSummary(session, created) {
+    const startedAtMs = Date.parse(session.startedAt);
+    const ageMs = Number.isFinite(startedAtMs) ? Date.now() - startedAtMs : null;
+    console.log('');
+    console.log(chalk.bold('Session'));
+    console.log(chalk.dim('────────────────────────────────────────'));
+    console.log(`  id:           ${session.id}`);
+    console.log(`  status:       ${created ? chalk.cyan('fresh (just created)') : chalk.green('active')}`);
+    console.log(`  started:      ${session.startedAt}`);
+    console.log(`  last activity: ${session.lastActivityAt}`);
+    if (ageMs !== null) {
+        console.log(`  age:          ${formatDuration(ageMs)}`);
+    }
+    console.log('');
+    console.log(`  touched files: ${Object.keys(session.touchedFiles).length}`);
+    console.log(`  events:        ${session.events.length}`);
+    console.log('');
+    console.log(chalk.dim('  Tip: run `projscan session touched` for the file list.'));
+}
+function printTouched(session, items, total) {
+    console.log('');
+    console.log(chalk.bold(`Touched files (${session.id.slice(0, 8)})`));
+    console.log(chalk.dim('────────────────────────────────────────'));
+    if (items.length === 0) {
+        console.log(chalk.dim('  No files touched in this session yet.'));
+        return;
+    }
+    for (const t of items) {
+        const sourceTag = formatSourceTag(t.source);
+        console.log(`  ${sourceTag} ${t.file}  ${chalk.dim(`(×${t.count}, ${t.lastTouchedAt})`)}`);
+    }
+    if (items.length < total) {
+        console.log('');
+        console.log(chalk.dim(`  ${total - items.length} more — pass --limit ${total} to see all.`));
+    }
+}
+function printEvents(session, items, total) {
+    console.log('');
+    console.log(chalk.bold(`Events (${session.id.slice(0, 8)})`));
+    console.log(chalk.dim('────────────────────────────────────────'));
+    if (items.length === 0) {
+        console.log(chalk.dim('  No events recorded in this session yet.'));
+        return;
+    }
+    for (const e of items) {
+        console.log(`  ${chalk.dim(e.at)}  ${e.kind}`);
+    }
+    if (items.length < total) {
+        console.log('');
+        console.log(chalk.dim(`  ${total - items.length} more — pass --limit ${total} to see all.`));
+    }
+}
+function formatSourceTag(source) {
+    switch (source) {
+        case 'tool-result':
+            return chalk.cyan('[tool]    ');
+        case 'fs-watch':
+            return chalk.yellow('[fs-watch]');
+        case 'explicit':
+            return chalk.magenta('[explicit]');
+        default:
+            return chalk.dim('[unknown] ');
+    }
+}
+function formatDuration(ms) {
+    if (ms < 1000)
+        return `${ms}ms`;
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60)
+        return `${seconds}s`;
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60)
+        return `${minutes}m ${seconds % 60}s`;
+    const hours = Math.floor(minutes / 60);
+    return `${hours}h ${minutes % 60}m`;
+}
+//# sourceMappingURL=session.js.map