swarmdo 1.15.0 → 1.16.0

package/.claude/helpers/statusline.cjs

@@ -515,7 +515,7 @@ function getCostFromStdin() {
 // misses, the displayed version is meaningful (matches what the user
 // installed), not a stale hard-coded string.
 function getPkgVersion() {
-  let ver = '1.15.0';
+  let ver = '1.16.0';
   try {
     const home = os.homedir();
     const pkgPaths = [

package/README.md

@@ -2,7 +2,7 @@
 
 [![swarmdo](swarmdo/assets/brand/logo-full.svg)](https://swarmdo.com)
 
-[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.15.0-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
+[![npm version (swarmdo)](https://img.shields.io/badge/npx%20swarmdo-v1.16.0-cb3837?style=for-the-badge&logo=npm&logoColor=white)](https://github.com/SwarmDo/swarmdo/releases)
 [![MIT License](https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge)](https://github.com/SwarmDo/swarmdo/blob/main/LICENSE)
 [![Website](https://img.shields.io/badge/swarmdo.com-e2a33c?style=for-the-badge&logoColor=black)](https://swarmdo.com)
 [![Star on GitHub](https://img.shields.io/github/stars/SwarmDo/swarmdo?style=for-the-badge&logo=github&color=gold)](https://github.com/SwarmDo/swarmdo)
@@ -284,6 +284,7 @@ The recent release train added a full day-to-day operations layer around the swa
 | `swarmdo license` | **Audit dependency licenses** — walk `node_modules`, resolve each package's SPDX license, and gate on an allow/deny policy so a GPL or unknown license can't slip into a permissive tree. `--allow MIT,Apache-2.0 --ci` fails the build; distinct from `security` (CVEs). Also an MCP tool (`license_check`). Deterministic |
 | `swarmdo sbom` | **Software Bill of Materials from the lockfile** — emit a CycloneDX (default) or SPDX JSON manifest of every dependency with version, purl, license, and integrity hash, for compliance/vuln tooling. `--spec spdx`, `-o sbom.json`, `--production`. Completes the env/license/sbom supply-chain trio. Deterministic |
 | `swarmdo apply` | **A forgiving `git apply`** — apply a unified diff with fuzzy context matching, so an agent's patch lands even when line numbers have drifted or a context line is slightly off, and reports exactly which hunks couldn't. `--dry-run` to preview, `--fuzz N` to tolerate more drift. Also an MCP tool (`apply_patch`). Deterministic |
+| `swarmdo hotspots` | **Change-risk hotspots from git history** — rank files by churn × recency × author-spread to surface the technical debt worth refactoring or testing, answered from data instead of a guess. `--since 90d`, `--by risk\|churn\|commits\|authors`, `--top N`, `--format json`. Pairs with `codegraph`; also an MCP tool (`hotspots`). Deterministic |
 | `swarmdo integrations` (alias `integrate`) | **Use swarmdo from Codex CLI, GitHub Copilot CLI, and pi** — one command wires AGENTS.md + each CLI's MCP config (idempotent, dry-run first, never touches your Claude Code setup) |
 | OpenRouter model pool | **Let swarms pick from any models you configure** — declare tier-mapped OpenRouter models in `swarmdo.config.json`; the router Thompson-samples among them per task and the execution layer dispatches the winner |
 | `swarmdo changelog` (alias `notes`) | **Release notes from conventional commits** — `--out NOTES.md` feeds `gh release create --notes-file` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmdo",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "description": "Swarmdo - Enterprise AI agent orchestration for Claude Code. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
   "main": "dist/index.js",
   "type": "module",

package/v3/@swarmdo/cli/dist/src/commands/apply.js

@@ -32,7 +32,10 @@ async function run(ctx) {
     const root = ctx.cwd || process.cwd();
     const dryRun = ctx.flags['dry-run'] === true;
     const partial = ctx.flags.partial === true;
-    const fuzz = typeof ctx.flags.fuzz === 'string' ? parseInt(ctx.flags.fuzz, 10) : 2;
+    // The parser may deliver --fuzz as a number or a string; accept both.
+    const fuzz = typeof ctx.flags.fuzz === 'number' ? ctx.flags.fuzz
+        : typeof ctx.flags.fuzz === 'string' ? parseInt(ctx.flags.fuzz, 10)
+            : 2;
     // Read the patch: a file arg, or stdin.
     let patchText;
     if (ctx.args[0]) {

package/v3/@swarmdo/cli/dist/src/commands/hotspots.d.ts

@@ -0,0 +1,17 @@
+/**
+ * `swarmdo hotspots` — rank files by change-risk mined from git history.
+ *
+ *   swarmdo hotspots                     # top risk files in the repo
+ *   swarmdo hotspots src --since 90d     # scope to a path + window
+ *   swarmdo hotspots --by churn --top 10 # sort/limit
+ *   swarmdo hotspots --format json       # machine-readable
+ *
+ * "Where is the technical debt?" answered from data: files that change often,
+ * churn heavily, are touched by many hands, and were edited recently. Pairs
+ * with `codegraph`. Engine (../hotspots/hotspots.ts) is pure + tested; this
+ * captures the git log.
+ */
+import type { Command } from '../types.js';
+export declare const hotspotsCommand: Command;
+export default hotspotsCommand;
+//# sourceMappingURL=hotspots.d.ts.map

package/v3/@swarmdo/cli/dist/src/commands/hotspots.js

@@ -0,0 +1,80 @@
+/**
+ * `swarmdo hotspots` — rank files by change-risk mined from git history.
+ *
+ *   swarmdo hotspots                     # top risk files in the repo
+ *   swarmdo hotspots src --since 90d     # scope to a path + window
+ *   swarmdo hotspots --by churn --top 10 # sort/limit
+ *   swarmdo hotspots --format json       # machine-readable
+ *
+ * "Where is the technical debt?" answered from data: files that change often,
+ * churn heavily, are touched by many hands, and were edited recently. Pairs
+ * with `codegraph`. Engine (../hotspots/hotspots.ts) is pure + tested; this
+ * captures the git log.
+ */
+import { execFileSync } from 'node:child_process';
+import { output } from '../output.js';
+import { parseGitLog, computeHotspots, formatHotspots } from '../hotspots/hotspots.js';
+const SORT_KEYS = ['risk', 'churn', 'commits', 'authors'];
+/** Read a numeric flag that the parser may deliver as a number OR a string. */
+function numFlag(v, def) {
+    const n = typeof v === 'number' ? v : typeof v === 'string' ? parseInt(v, 10) : NaN;
+    return Number.isFinite(n) ? n : def;
+}
+async function run(ctx) {
+    const root = ctx.cwd || process.cwd();
+    const pathArg = ctx.args[0];
+    const since = typeof ctx.flags.since === 'string' ? ctx.flags.since : '1 year ago';
+    const top = numFlag(ctx.flags.top, 20);
+    const minCommits = numFlag(ctx.flags['min-commits'], 1);
+    const by = (typeof ctx.flags.by === 'string' ? ctx.flags.by : 'risk');
+    if (!SORT_KEYS.includes(by)) {
+        output.printError(`unknown --by '${by}' (use ${SORT_KEYS.join('|')})`);
+        return { success: false, exitCode: 1 };
+    }
+    // Global --format (text|json|table); text and table both render the table.
+    const asJson = ctx.flags.format === 'json';
+    // Capture history: SOH-delimited header + numstat, no merges.
+    const args = ['log', '--no-merges', '--numstat', `--since=${since}`, '--format=format:%x01%H%x1f%an%x1f%aI'];
+    if (pathArg)
+        args.push('--', pathArg);
+    let raw;
+    try {
+        raw = execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 128 * 1024 * 1024 });
+    }
+    catch {
+        output.printError('git log failed — is this a git repository?');
+        return { success: false, exitCode: 1 };
+    }
+    const now = Date.now();
+    const spots = computeHotspots(parseGitLog(raw), now, { by, top: top > 0 ? top : undefined, minCommits });
+    if (asJson) {
+        process.stdout.write(JSON.stringify({ generated: new Date(now).toISOString(), by, count: spots.length, hotspots: spots }, null, 2) + '\n');
+    }
+    else {
+        if (spots.length === 0) {
+            output.writeln(output.dim('no hotspots found — no matching git history in the window'));
+        }
+        else {
+            output.writeln(output.bold(`Change-risk hotspots (by ${by}, since ${since})`));
+            output.writeln(formatHotspots(spots, now));
+        }
+    }
+    return { success: true, exitCode: 0 };
+}
+export const hotspotsCommand = {
+    name: 'hotspots',
+    description: 'Rank files by change-risk mined from git history (churn × recency × author-spread) — find the technical debt worth refactoring or testing',
+    options: [
+        { name: 'since', description: 'history window, e.g. 90d or "3 months ago" (default 1 year)', type: 'string' },
+        { name: 'top', description: 'keep only the top N files (default 20; 0 = all)', type: 'string' },
+        { name: 'min-commits', description: 'drop files with fewer than N commits (default 1)', type: 'string' },
+        { name: 'by', description: `sort key: ${SORT_KEYS.join('|')} (default risk)`, type: 'string' },
+    ],
+    examples: [
+        { command: 'swarmdo hotspots src --since 90d', description: 'Risk hotspots under src/ in the last 90 days' },
+        { command: 'swarmdo hotspots --by churn --top 10 --format json', description: 'Top-10 by churn as JSON' },
+    ],
+    action: run,
+};
+export default hotspotsCommand;
+//# sourceMappingURL=hotspots.js.map

package/v3/@swarmdo/cli/dist/src/commands/index.js

@@ -41,6 +41,9 @@ const commandLoaders = {
     // Fuzzy unified-diff applier (agent-diff pain) — a forgiving `git apply` that
     // lands hunks despite context drift and reports what it couldn't.
     apply: () => import('./apply.js'),
+    // Change-risk hotspots from git history (code-maat demand) — rank files by
+    // churn × recency × author-spread; "where is the tech debt?" from data.
+    hotspots: () => import('./hotspots.js'),
     // Queryable exported-symbol index (codegraph demand) — where things are
     // defined without grep+read round-trips.
     codegraph: () => import('./codegraph.js'),
@@ -274,7 +277,7 @@ export async function getCommandsByCategory() {
     // three slots from 'statusline' onward (completionsCmd received the
     // statusline module, analyzeCmd received completions, …), scrambling the
     // categorized help. Every load now has a named slot.
-    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, swarmvectorCmd, hiveMindCmd, configCmd, statuslineCmd, compressCmd, efficiencyCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd, demoCmd, usageCmd, repairCmd, hudCmd, compactCmd, codegraphCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd,] = await Promise.all([
+    const [daemonCmd, doctorCmd, embeddingsCmd, neuralCmd, performanceCmd, securityCmd, swarmvectorCmd, hiveMindCmd, configCmd, statuslineCmd, compressCmd, efficiencyCmd, completionsCmd, migrateCmd, workflowCmd, analyzeCmd, routeCmd, progressCmd, providersCmd, pluginsCmd, deploymentCmd, claimsCmd, issuesCmd, updateCmd, processCmd, guidanceCmd, applianceCmd, cleanupCmd, autopilotCmd, demoCmd, usageCmd, repairCmd, hudCmd, compactCmd, codegraphCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd,] = await Promise.all([
         loadCommand('daemon'), loadCommand('doctor'), loadCommand('embeddings'), loadCommand('neural'),
         loadCommand('performance'), loadCommand('security'), loadCommand('swarmvector'), loadCommand('hive-mind'),
         loadCommand('config'), loadCommand('statusline'), loadCommand('compress'), loadCommand('efficiency'),
@@ -282,7 +285,7 @@ export async function getCommandsByCategory() {
         loadCommand('analyze'), loadCommand('route'), loadCommand('progress'), loadCommand('providers'),
         loadCommand('plugins'), loadCommand('deployment'), loadCommand('claims'), loadCommand('issues'),
         loadCommand('update'), loadCommand('process'), loadCommand('guidance'), loadCommand('appliance'),
-        loadCommand('cleanup'), loadCommand('autopilot'), loadCommand('demo'), loadCommand('usage'), loadCommand('repair'), loadCommand('hud'), loadCommand('compact'), loadCommand('codegraph'), loadCommand('redact'), loadCommand('pack'), loadCommand('env'), loadCommand('license'), loadCommand('sbom'), loadCommand('apply'),
+        loadCommand('cleanup'), loadCommand('autopilot'), loadCommand('demo'), loadCommand('usage'), loadCommand('repair'), loadCommand('hud'), loadCommand('compact'), loadCommand('codegraph'), loadCommand('redact'), loadCommand('pack'), loadCommand('env'), loadCommand('license'), loadCommand('sbom'), loadCommand('apply'), loadCommand('hotspots'),
     ]);
     return {
         primary: [
@@ -298,7 +301,7 @@ export async function getCommandsByCategory() {
         utility: [
             configCmd, doctorCmd, daemonCmd, completionsCmd,
             migrateCmd, workflowCmd, demoCmd,
-            statuslineCmd, compressCmd, compactCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, efficiencyCmd,
+            statuslineCmd, compressCmd, compactCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, efficiencyCmd,
         ].filter(Boolean),
         analysis: [
             analyzeCmd, routeCmd, progressCmd, usageCmd, hudCmd, codegraphCmd,

package/v3/@swarmdo/cli/dist/src/hotspots/hotspots.d.ts

@@ -0,0 +1,54 @@
+/**
+ * hotspots.ts — rank files by CHANGE-RISK mined from git history.
+ *
+ * The "where is the technical debt?" query, answered from data instead of a
+ * guess: files that change often, are churned heavily, are touched by many
+ * hands, and were edited recently are the ones most worth refactoring, testing,
+ * or reviewing carefully. Inspired by code-maat / "Your Code as a Crime Scene".
+ *
+ * Pure + deterministic: the scoring core takes the raw `git log --numstat`
+ * string (+ a fixed `now` for recency) and folds it into a ranked list. No LLM,
+ * no network — the git subprocess lives in ../commands/hotspots.ts, so this
+ * module is fully fixture-testable.
+ *
+ * Expected log format (control-char delimited to avoid collisions):
+ *   <SOH>%H<US>%an<US>%aI      ← one header line per commit
+ *   <added>\t<deleted>\t<path> ← one numstat line per file ('-' for binary)
+ */
+export interface CommitFile {
+    path: string;
+    added: number;
+    deleted: number;
+}
+export interface Commit {
+    hash: string;
+    author: string;
+    /** epoch milliseconds, parsed from the ISO author date */
+    date: number;
+    files: CommitFile[];
+}
+export interface FileHotspot {
+    path: string;
+    commits: number;
+    churn: number;
+    authors: number;
+    lastTouched: number;
+    firstTouched: number;
+    risk: number;
+}
+export type SortKey = 'risk' | 'churn' | 'commits' | 'authors';
+export interface HotspotOptions {
+    /** drop files with fewer than this many commits (default 1) */
+    minCommits?: number;
+    /** sort key (default 'risk') */
+    by?: SortKey;
+    /** keep only the top N after sorting (default: all) */
+    top?: number;
+}
+/** Parse a control-char-delimited `git log --numstat` dump into commits. Pure. */
+export declare function parseGitLog(raw: string): Commit[];
+/** Aggregate commits into per-file hotspots, scored and ranked. Pure. */
+export declare function computeHotspots(commits: Commit[], now: number, opts?: HotspotOptions): FileHotspot[];
+/** Human-readable table. Pure. */
+export declare function formatHotspots(spots: FileHotspot[], now: number): string;
+//# sourceMappingURL=hotspots.d.ts.map

package/v3/@swarmdo/cli/dist/src/hotspots/hotspots.js

@@ -0,0 +1,122 @@
+/**
+ * hotspots.ts — rank files by CHANGE-RISK mined from git history.
+ *
+ * The "where is the technical debt?" query, answered from data instead of a
+ * guess: files that change often, are churned heavily, are touched by many
+ * hands, and were edited recently are the ones most worth refactoring, testing,
+ * or reviewing carefully. Inspired by code-maat / "Your Code as a Crime Scene".
+ *
+ * Pure + deterministic: the scoring core takes the raw `git log --numstat`
+ * string (+ a fixed `now` for recency) and folds it into a ranked list. No LLM,
+ * no network — the git subprocess lives in ../commands/hotspots.ts, so this
+ * module is fully fixture-testable.
+ *
+ * Expected log format (control-char delimited to avoid collisions):
+ *   <SOH>%H<US>%an<US>%aI      ← one header line per commit
+ *   <added>\t<deleted>\t<path> ← one numstat line per file ('-' for binary)
+ */
+const SOH = '\x01'; // start-of-commit marker (git --format=format:%x01...)
+const US = '\x1f'; // field separator (%x1f)
+/** Parse a control-char-delimited `git log --numstat` dump into commits. Pure. */
+export function parseGitLog(raw) {
+    const commits = [];
+    let cur = null;
+    for (const line of raw.split('\n')) {
+        if (line === '')
+            continue;
+        if (line.startsWith(SOH)) {
+            const [hash, author, iso] = line.slice(1).split(US);
+            const t = Date.parse(iso ?? '');
+            cur = { hash: hash ?? '', author: author ?? '', date: Number.isNaN(t) ? 0 : t, files: [] };
+            commits.push(cur);
+            continue;
+        }
+        if (!cur)
+            continue;
+        // numstat: added<TAB>deleted<TAB>path  ('-' means binary → count as 0
+        const tab1 = line.indexOf('\t');
+        const tab2 = line.indexOf('\t', tab1 + 1);
+        if (tab1 < 0 || tab2 < 0)
+            continue;
+        const a = line.slice(0, tab1);
+        const d = line.slice(tab1 + 1, tab2);
+        const path = line.slice(tab2 + 1);
+        if (!path)
+            continue;
+        cur.files.push({ path, added: a === '-' ? 0 : parseInt(a, 10) || 0, deleted: d === '-' ? 0 : parseInt(d, 10) || 0 });
+    }
+    return commits;
+}
+/**
+ * Composite risk score. Deterministic and monotonic:
+ *   risk = commits · log2(1 + churn) · authorFactor · recencyWeight
+ * where authorFactor = 1 + log2(authors) (coordination cost of many hands)
+ * and recencyWeight = 1 / (1 + ageDays/30) (recent churn is riskier; decays
+ * over a ~month scale). `now` is injected so the function is pure/testable.
+ */
+function scoreOf(h, now) {
+    const authorFactor = 1 + Math.log2(h.authors);
+    const ageDays = Math.max(0, (now - h.lastTouched) / 86_400_000);
+    const recencyWeight = 1 / (1 + ageDays / 30);
+    const raw = h.commits * Math.log2(1 + h.churn) * authorFactor * recencyWeight;
+    return Math.round(raw * 100) / 100;
+}
+/** Aggregate commits into per-file hotspots, scored and ranked. Pure. */
+export function computeHotspots(commits, now, opts = {}) {
+    const minCommits = opts.minCommits ?? 1;
+    const by = opts.by ?? 'risk';
+    const acc = new Map();
+    for (const c of commits) {
+        for (const f of c.files) {
+            let a = acc.get(f.path);
+            if (!a) {
+                a = { commits: 0, churn: 0, authors: new Set(), lastTouched: 0, firstTouched: Infinity };
+                acc.set(f.path, a);
+            }
+            a.commits += 1;
+            a.churn += f.added + f.deleted;
+            a.authors.add(c.author);
+            if (c.date > a.lastTouched)
+                a.lastTouched = c.date;
+            if (c.date < a.firstTouched)
+                a.firstTouched = c.date;
+        }
+    }
+    let out = [];
+    for (const [path, a] of acc) {
+        if (a.commits < minCommits)
+            continue;
+        const base = {
+            path,
+            commits: a.commits,
+            churn: a.churn,
+            authors: a.authors.size,
+            lastTouched: a.lastTouched,
+            firstTouched: a.firstTouched === Infinity ? 0 : a.firstTouched,
+        };
+        out.push({ ...base, risk: scoreOf(base, now) });
+    }
+    // Deterministic sort: chosen key desc, then path asc for stable ties.
+    out.sort((x, y) => y[by] - x[by] || (x.path < y.path ? -1 : x.path > y.path ? 1 : 0));
+    if (opts.top && opts.top > 0)
+        out = out.slice(0, opts.top);
+    return out;
+}
+/** Human-readable table. Pure. */
+export function formatHotspots(spots, now) {
+    if (spots.length === 0)
+        return 'no hotspots found (no matching history)';
+    const lines = [];
+    lines.push(`rank  risk    commits  churn   authors  file`);
+    spots.forEach((s, i) => {
+        const ageDays = Math.round((now - s.lastTouched) / 86_400_000);
+        const rank = String(i + 1).padStart(4);
+        const risk = s.risk.toFixed(2).padStart(7);
+        const commits = String(s.commits).padStart(7);
+        const churn = String(s.churn).padStart(6);
+        const authors = String(s.authors).padStart(7);
+        lines.push(`${rank}  ${risk}  ${commits}  ${churn}  ${authors}  ${s.path}  ${ageDays === 0 ? '(today)' : `(${ageDays}d ago)`}`);
+    });
+    return lines.join('\n');
+}
+//# sourceMappingURL=hotspots.js.map

package/v3/@swarmdo/cli/dist/src/mcp-client.js

@@ -24,6 +24,7 @@ import { redactTools } from './mcp-tools/redact-tools.js';
 import { envTools } from './mcp-tools/env-tools.js';
 import { licenseTools } from './mcp-tools/license-tools.js';
 import { applyTools } from './mcp-tools/apply-tools.js';
+import { hotspotsTools } from './mcp-tools/hotspots-tools.js';
 import { progressTools } from './mcp-tools/progress-tools.js';
 import { embeddingsTools } from './mcp-tools/embeddings-tools.js';
 import { claimsTools } from './mcp-tools/claims-tools.js';
@@ -112,6 +113,7 @@ const TOOL_GROUPS = {
     env: () => envTools,
     license: () => licenseTools,
     apply: () => applyTools,
+    hotspots: () => hotspotsTools,
     progress: () => progressTools,
     embeddings: () => embeddingsTools,
     claims: () => claimsTools,

package/v3/@swarmdo/cli/dist/src/mcp-tools/hotspots-tools.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Hotspots MCP Tool
+ *
+ * Let an agent ask "which files carry the most change-risk?" and get ranked
+ * JSON — files that change often, churn heavily, are touched by many hands, and
+ * were edited recently. Data-driven "where is the tech debt?" so an agent can
+ * focus refactoring/testing/review effort. Shares the pure engine in
+ * ../hotspots/hotspots.ts with the CLI; captures git history via subprocess.
+ */
+import type { MCPTool } from './types.js';
+export declare const hotspotsTools: MCPTool[];
+//# sourceMappingURL=hotspots-tools.d.ts.map

package/v3/@swarmdo/cli/dist/src/mcp-tools/hotspots-tools.js

@@ -0,0 +1,51 @@
+/**
+ * Hotspots MCP Tool
+ *
+ * Let an agent ask "which files carry the most change-risk?" and get ranked
+ * JSON — files that change often, churn heavily, are touched by many hands, and
+ * were edited recently. Data-driven "where is the tech debt?" so an agent can
+ * focus refactoring/testing/review effort. Shares the pure engine in
+ * ../hotspots/hotspots.ts with the CLI; captures git history via subprocess.
+ */
+import { execFileSync } from 'node:child_process';
+import { parseGitLog, computeHotspots } from '../hotspots/hotspots.js';
+const SORT_KEYS = ['risk', 'churn', 'commits', 'authors'];
+const hotspotsTool = {
+    name: 'hotspots',
+    description: 'Rank files by change-risk mined from git history (churn × recency × author-spread). Returns ranked JSON — call this to find the technical debt worth refactoring or testing before you start, instead of guessing. Runs in a git repository.',
+    category: 'hotspots',
+    tags: ['git', 'risk', 'churn', 'refactor', 'debt'],
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'repo path to run in (default cwd)' },
+            subpath: { type: 'string', description: 'limit history to this subdirectory/file' },
+            since: { type: 'string', description: 'history window, e.g. 90d or "3 months ago" (default 1 year)' },
+            top: { type: 'number', description: 'keep only the top N files (default 20)' },
+            by: { type: 'string', enum: SORT_KEYS, description: 'sort key (default risk)' },
+            minCommits: { type: 'number', description: 'drop files with fewer than N commits (default 1)' },
+        },
+    },
+    handler: async (params) => {
+        const cwd = typeof params.path === 'string' ? params.path : process.cwd();
+        const since = typeof params.since === 'string' ? params.since : '1 year ago';
+        const by = (typeof params.by === 'string' && SORT_KEYS.includes(params.by) ? params.by : 'risk');
+        const top = typeof params.top === 'number' ? params.top : 20;
+        const minCommits = typeof params.minCommits === 'number' ? params.minCommits : 1;
+        const args = ['log', '--no-merges', '--numstat', `--since=${since}`, '--format=format:%x01%H%x1f%an%x1f%aI'];
+        if (typeof params.subpath === 'string' && params.subpath)
+            args.push('--', params.subpath);
+        let raw;
+        try {
+            raw = execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'], maxBuffer: 128 * 1024 * 1024 });
+        }
+        catch {
+            return { error: true, message: 'git log failed — not a git repository?' };
+        }
+        const now = Date.now();
+        const hotspots = computeHotspots(parseGitLog(raw), now, { by, top: top > 0 ? top : undefined, minCommits });
+        return { by, count: hotspots.length, hotspots };
+    },
+};
+export const hotspotsTools = [hotspotsTool];
+//# sourceMappingURL=hotspots-tools.js.map

package/v3/@swarmdo/cli/dist/src/mcp-tools/index.d.ts

@@ -20,6 +20,7 @@ export { redactTools } from './redact-tools.js';
 export { envTools } from './env-tools.js';
 export { licenseTools } from './license-tools.js';
 export { applyTools } from './apply-tools.js';
+export { hotspotsTools } from './hotspots-tools.js';
 export { progressTools } from './progress-tools.js';
 export { transferTools } from './transfer-tools.js';
 export { securityTools } from './security-tools.js';

package/v3/@swarmdo/cli/dist/src/mcp-tools/index.js

@@ -19,6 +19,7 @@ export { redactTools } from './redact-tools.js';
 export { envTools } from './env-tools.js';
 export { licenseTools } from './license-tools.js';
 export { applyTools } from './apply-tools.js';
+export { hotspotsTools } from './hotspots-tools.js';
 export { progressTools } from './progress-tools.js';
 export { transferTools } from './transfer-tools.js';
 export { securityTools } from './security-tools.js';

package/v3/@swarmdo/cli/dist/src/mcp-tools/profiles.js

@@ -26,6 +26,7 @@ const LEAN_GROUPS = [
     'redact', // redact_text / redact_scan — secret guard on the data path
     'env', // env_check — env-var drift (missing/unused/undocumented)
     'apply', // apply_patch — fuzzy unified-diff applier for agent edits
+    'hotspots', // hotspots — git-history change-risk ranking ("where's the debt?")
 ];
 /** Balanced = lean + orchestration/session/system the average user reaches for. */
 const BALANCED_EXTRA = [

package/v3/@swarmdo/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@swarmdo/cli",
-  "version": "1.15.0",
+  "version": "1.16.0",
   "type": "module",
   "description": "Swarmdo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
   "main": "dist/src/index.js",