swarmdo 1.37.0 → 1.45.0

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

@@ -759,6 +759,60 @@ const graphCommand = {
         return { success: true };
     }
 };
+// Doctor subcommand — classify blocked tasks live vs dead + a global deadlock
+// verdict (task-deps.ts::taskDagHealth). Airflow's upstream_failed + DAG
+// deadlock detection: surfaces a task that can NEVER run because a prerequisite
+// failed/was cancelled/is missing, and a whole-graph stall a dispatch loop would
+// otherwise spin on forever.
+const doctorCommand = {
+    name: 'doctor',
+    aliases: ['health'],
+    description: 'Diagnose the task DAG: which blocked tasks can still run (live) vs are permanently stuck because a dependency failed/was cancelled/is missing (dead), and whether the whole graph is deadlocked',
+    options: [
+        { name: 'json', description: 'Machine-readable output', type: 'boolean', default: false },
+        { name: 'ci', description: 'Exit 1 if the DAG is deadlocked or any task is permanently (dead) blocked — gate a dispatch loop', type: 'boolean', default: false }
+    ],
+    examples: [
+        { command: 'swarmdo task doctor', description: 'Show live-blocked vs dead-blocked tasks and any deadlock' },
+        { command: 'swarmdo task doctor --ci', description: 'Fail (exit 1) when the task graph is stuck' }
+    ],
+    action: async (ctx) => {
+        const { loadTaskStore } = await import('../mcp-tools/task-tools.js');
+        const { taskDagHealth } = await import('../mcp-tools/task-deps.js');
+        const store = loadTaskStore(ctx.cwd);
+        const health = taskDagHealth(store);
+        const stuck = health.deadlocked || health.deadBlocked.length > 0;
+        const code = ctx.flags.ci === true && stuck ? 1 : 0;
+        if (ctx.flags.json === true) {
+            output.printJson({
+                deadlocked: health.deadlocked,
+                liveBlocked: health.liveBlocked.map(t => t.taskId),
+                deadBlocked: health.deadBlocked.map(d => ({ taskId: d.task.taskId, rootCause: d.rootCause })),
+            });
+            return { success: code === 0, exitCode: code, data: health };
+        }
+        output.writeln();
+        if (health.deadlocked) {
+            output.writeln(output.error('⚠ DEADLOCKED') + output.dim(' — pending work exists but nothing is ready and nothing is running'));
+            output.writeln();
+        }
+        output.writeln(output.bold(`Live-blocked (${health.liveBlocked.length})`) + output.dim(' — waiting on deps that can still complete'));
+        for (const t of health.liveBlocked) {
+            output.writeln(`  ${output.dim('○')} ${t.taskId}  ${t.description.slice(0, 60)}`);
+        }
+        output.writeln();
+        output.writeln(output.bold(`Dead-blocked (${health.deadBlocked.length})`) + output.dim(' — a prerequisite failed/was cancelled/is missing; will NEVER run without intervention'));
+        for (const d of health.deadBlocked) {
+            output.writeln(`  ${output.error('✗')} ${d.task.taskId} ⇐ dead: ${d.rootCause.join(', ') || '(cycle)'}`);
+        }
+        if (!stuck) {
+            output.writeln();
+            output.printSuccess('task graph healthy — no permanent blocks or deadlock');
+        }
+        output.writeln();
+        return { success: code === 0, exitCode: code, data: health };
+    }
+};
 // parse-prd subcommand — decompose a PRD/spec doc into the task DAG (Task Master
 // parity). The LLM decomposition lives in ../task/parse-prd.ts (injectable +
 // unit-tested); this layer gates the billable call and creates the linked tasks.
@@ -890,7 +944,7 @@ const parsePrdCommand = {
 export const taskCommand = {
     name: 'task',
     description: 'Task management commands',
-    subcommands: [createCommand, parsePrdCommand, listCommand, statusCommand, cancelCommand, assignCommand, retryCommand, dispatchCommand, readyCommand, graphCommand],
+    subcommands: [createCommand, parsePrdCommand, listCommand, statusCommand, cancelCommand, assignCommand, retryCommand, dispatchCommand, readyCommand, graphCommand, doctorCommand],
     options: [],
     examples: [
         { command: 'swarmdo task create -t implementation -d "Add user auth"', description: 'Create a task' },
@@ -917,7 +971,8 @@ export const taskCommand = {
             `${output.highlight('assign')}  - Assign task to agent(s)`,
             `${output.highlight('retry')}   - Retry a failed task`,
             `${output.highlight('ready')}   - List ready vs dependency-blocked tasks`,
-            `${output.highlight('graph')}   - Show the dependency graph`
+            `${output.highlight('graph')}   - Show the dependency graph`,
+            `${output.highlight('doctor')}  - Diagnose live vs dead blocks + deadlock (--ci gates)`
         ]);
         output.writeln();
         output.writeln('Run "swarmdo task <subcommand> --help" for subcommand help');

package/v3/@swarmdo/cli/dist/src/config-lint/agents-lint.d.ts

@@ -0,0 +1,30 @@
+/**
+ * agents-lint.ts — static validation of Claude Code subagent definitions
+ * (`.claude/agents/*.md`).
+ *
+ * Each subagent file is YAML frontmatter (`name` + `description` required;
+ * `tools`, `model` optional) plus a system-prompt body. Claude Code SILENTLY
+ * ignores a subagent whose frontmatter is malformed, whose `name` collides with
+ * another file, or whose `model` is invalid — so "why isn't my subagent
+ * loading?" is an undebuggable footgun, and users mass-copy these files from
+ * large community collections where typos ride along. This catches those
+ * before CC does.
+ *
+ * Pure: parsed text in, findings out — same `Finding` shape + report machinery
+ * as the rest of config-lint; the command layer only reads files.
+ */
+import type { Finding } from './lint.js';
+/** Models a Claude Code subagent `model:` field may name. */
+export declare const AGENT_MODELS: string[];
+/** Lint ONE subagent file's raw text. Pure. */
+export declare function lintAgentFile(file: string, raw: string): Finding[];
+export interface AgentFile {
+    file: string;
+    raw: string;
+}
+/**
+ * Lint a set of subagent files: every per-file rule PLUS cross-file duplicate
+ * `name` detection (Claude Code loads only one of a colliding pair). Pure.
+ */
+export declare function lintAgents(files: AgentFile[]): Finding[];
+//# sourceMappingURL=agents-lint.d.ts.map

package/v3/@swarmdo/cli/dist/src/config-lint/agents-lint.js

@@ -0,0 +1,87 @@
+/**
+ * agents-lint.ts — static validation of Claude Code subagent definitions
+ * (`.claude/agents/*.md`).
+ *
+ * Each subagent file is YAML frontmatter (`name` + `description` required;
+ * `tools`, `model` optional) plus a system-prompt body. Claude Code SILENTLY
+ * ignores a subagent whose frontmatter is malformed, whose `name` collides with
+ * another file, or whose `model` is invalid — so "why isn't my subagent
+ * loading?" is an undebuggable footgun, and users mass-copy these files from
+ * large community collections where typos ride along. This catches those
+ * before CC does.
+ *
+ * Pure: parsed text in, findings out — same `Finding` shape + report machinery
+ * as the rest of config-lint; the command layer only reads files.
+ */
+import { parse as parseYaml } from 'yaml';
+const f = (file, severity, rule, message) => ({ file, severity, rule, message });
+/** Models a Claude Code subagent `model:` field may name. */
+export const AGENT_MODELS = ['sonnet', 'opus', 'haiku', 'inherit'];
+// Leading (optional BOM) `---` fence, YAML body (non-greedy) up to a closing
+// `---` on its own line, then the optional system-prompt body. CRLF-tolerant.
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/;
+function parseAgent(raw) {
+    const m = raw.replace(/^\uFEFF/, "").match(FRONTMATTER_RE);
+    if (!m)
+        return { meta: null, body: '', malformed: 'no YAML frontmatter block (a subagent file must start with `---` … `---`)' };
+    const body = m[2] ?? '';
+    let fm;
+    try {
+        fm = parseYaml(m[1]);
+    }
+    catch (e) {
+        return { meta: null, body, malformed: `frontmatter is not valid YAML: ${e.message}` };
+    }
+    if (fm === null || typeof fm !== 'object' || Array.isArray(fm)) {
+        return { meta: null, body, malformed: 'frontmatter must be a YAML mapping of key: value' };
+    }
+    return { meta: fm, body };
+}
+function lintParsed(file, p) {
+    if (p.malformed)
+        return [f(file, 'error', 'agent-malformed-frontmatter', p.malformed)];
+    const out = [];
+    const meta = p.meta;
+    if (typeof meta.name !== 'string' || meta.name.trim() === '') {
+        out.push(f(file, 'error', 'agent-missing-name', 'frontmatter is missing a non-empty `name`'));
+    }
+    if (typeof meta.description !== 'string' || meta.description.trim() === '') {
+        out.push(f(file, 'error', 'agent-missing-description', 'frontmatter is missing a non-empty `description` (Claude Code routes to a subagent by its description)'));
+    }
+    if (meta.model !== undefined && !AGENT_MODELS.includes(String(meta.model))) {
+        out.push(f(file, 'error', 'agent-bad-model', `model "${String(meta.model)}" is not one of: ${AGENT_MODELS.join(', ')}`));
+    }
+    if (p.body.trim() === '') {
+        out.push(f(file, 'warn', 'agent-empty-body', 'no system prompt below the frontmatter — the subagent has no instructions'));
+    }
+    return out;
+}
+/** Lint ONE subagent file's raw text. Pure. */
+export function lintAgentFile(file, raw) {
+    return lintParsed(file, parseAgent(raw));
+}
+/**
+ * Lint a set of subagent files: every per-file rule PLUS cross-file duplicate
+ * `name` detection (Claude Code loads only one of a colliding pair). Pure.
+ */
+export function lintAgents(files) {
+    const out = [];
+    const nameToFiles = new Map();
+    for (const { file, raw } of files) {
+        const p = parseAgent(raw);
+        out.push(...lintParsed(file, p));
+        const name = p.meta && typeof p.meta.name === 'string' ? p.meta.name.trim() : '';
+        if (name) {
+            const arr = nameToFiles.get(name) ?? [];
+            arr.push(file);
+            nameToFiles.set(name, arr);
+        }
+    }
+    for (const [name, group] of nameToFiles) {
+        if (group.length > 1) {
+            out.push(f(group[0], 'error', 'agent-duplicate-name', `subagent name "${name}" is declared by ${group.length} files (${group.join(', ')}) — Claude Code loads only one; rename the rest`));
+        }
+    }
+    return out;
+}
+//# sourceMappingURL=agents-lint.js.map

package/v3/@swarmdo/cli/dist/src/config-lint/lint.d.ts

@@ -17,6 +17,7 @@ export interface Finding {
 }
 export declare const TOPOLOGIES: string[];
 export declare const MEMORY_BACKENDS: string[];
+import { type AgentFile } from './agents-lint.js';
 export declare const KNOWN_CONFIG_KEYS: string[];
 export declare const HOOK_EVENTS: string[];
 /** Parse a JSON file's raw text; a null raw means "file absent" (fine). */
@@ -49,6 +50,8 @@ export interface LintInput {
     /** entries under `.claude/commands/sDo/` — used to identify flat pre-1.4 twins */
     sdoCommands?: string[];
     skills?: string[];
+    /** `.claude/agents/*.md` subagent definitions (raw text per file) */
+    agentFiles?: AgentFile[];
 }
 export interface LintReport {
     findings: Finding[];

package/v3/@swarmdo/cli/dist/src/config-lint/lint.js

@@ -12,6 +12,7 @@ const f = (file, severity, rule, message) => ({ file, severity, rule, message })
 export const TOPOLOGIES = ['hierarchical', 'mesh', 'hierarchical-mesh', 'ring', 'star', 'hybrid', 'adaptive'];
 export const MEMORY_BACKENDS = ['agentdb', 'sqlite', 'hybrid', 'memory'];
 import { parseOpenRouterConfig } from '../providers/openrouter-config.js';
+import { lintAgents } from './agents-lint.js';
 export const KNOWN_CONFIG_KEYS = ['topology', 'maxAgents', 'strategy', 'consensus', 'memory', 'memoryBackend', 'hnsw', 'neural', 'embeddings', 'providers', 'mcp', 'logging', 'daemon', 'hooks', 'version', 'openrouter', '$schema'];
 // Current Claude Code hook events (source: code.claude.com/docs/en/hooks).
 // Kept in sync with the runtime; a stale list here false-warns on valid hooks.
@@ -194,6 +195,8 @@ export function lintAll(input) {
         findings.push(...jf, ...lintMcpConfig(input.mcpConfig.file, obj));
     }
     findings.push(...lintLegacyLayout(input.commandsRoot ?? [], input.skills ?? [], input.sdoCommands ?? []));
+    if (input.agentFiles?.length)
+        findings.push(...lintAgents(input.agentFiles));
     return {
         findings,
         errors: findings.filter((x) => x.severity === 'error').length,

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

@@ -0,0 +1,56 @@
+/**
+ * coupling.ts — temporal (co-change) coupling mined from git history.
+ *
+ * "Which files change together?" — the EMPIRICAL complement to `affected`'s
+ * STATIC import graph. Files that repeatedly land in the same commit are
+ * coupled in practice even when no import edge connects them (a JSON schema and
+ * its TS type, a serializer/deserializer split across modules, a feature flag
+ * and its consumers, a doc that must track an API). Surfacing that lets an agent
+ * or a maintainer catch the edit they'd otherwise forget.
+ *
+ * This is code-maat's `coupling`/`soc` analysis (Tornhill, *Your Code as a
+ * Crime Scene*), productized as "Change Coupling" in CodeScene. The scoring core
+ * is a pure fold over the SAME `git log --numstat` dump `hotspots` already
+ * parses, so it reuses that Commit type + parseGitLog and is unit-tested without
+ * a repo.
+ */
+import type { Commit } from '../hotspots/hotspots.js';
+export interface CouplingPair {
+    /** the lexicographically smaller path of the pair */
+    a: string;
+    /** the lexicographically larger path of the pair */
+    b: string;
+    /** commits touching BOTH a and b */
+    shared: number;
+    /** commits touching a (within the file cap) */
+    aCommits: number;
+    /** commits touching b (within the file cap) */
+    bCommits: number;
+    /** shared / min(aCommits, bCommits) ∈ (0,1]; 1.0 = they never move apart */
+    degree: number;
+}
+export interface CouplingOptions {
+    /** drop pairs sharing fewer than this many commits (default 2) — support threshold */
+    minShared?: number;
+    /**
+     * skip commits touching more than this many files (default 30; 0 = no cap).
+     * A sweeping rename/format/license commit would otherwise couple everything
+     * it touches — the code-maat noise convention drops those wide commits.
+     */
+    maxFiles?: number;
+    /** keep only the top N pairs after ranking (default: all) */
+    top?: number;
+    /** keep only pairs involving this exact path (a "what couples with X?" query) */
+    focus?: string;
+}
+/**
+ * Rank co-changing file pairs. Pure + deterministic.
+ *
+ * degree(A,B) = shared / min(commits(A), commits(B)) — the fraction of the
+ * rarer file's commits that also touched the other. Symmetric, in (0,1].
+ */
+export declare function computeCoupling(commits: Commit[], opts?: CouplingOptions): CouplingPair[];
+export declare function couplingToCsv(pairs: CouplingPair[]): string;
+/** Human-readable table. Pure. */
+export declare function formatCoupling(pairs: CouplingPair[]): string;
+//# sourceMappingURL=coupling.d.ts.map

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

@@ -0,0 +1,86 @@
+/**
+ * coupling.ts — temporal (co-change) coupling mined from git history.
+ *
+ * "Which files change together?" — the EMPIRICAL complement to `affected`'s
+ * STATIC import graph. Files that repeatedly land in the same commit are
+ * coupled in practice even when no import edge connects them (a JSON schema and
+ * its TS type, a serializer/deserializer split across modules, a feature flag
+ * and its consumers, a doc that must track an API). Surfacing that lets an agent
+ * or a maintainer catch the edit they'd otherwise forget.
+ *
+ * This is code-maat's `coupling`/`soc` analysis (Tornhill, *Your Code as a
+ * Crime Scene*), productized as "Change Coupling" in CodeScene. The scoring core
+ * is a pure fold over the SAME `git log --numstat` dump `hotspots` already
+ * parses, so it reuses that Commit type + parseGitLog and is unit-tested without
+ * a repo.
+ */
+import { toCsv } from '../util/csv.js';
+const US = '\x1f'; // pair-key separator (never appears in a file path)
+/**
+ * Rank co-changing file pairs. Pure + deterministic.
+ *
+ * degree(A,B) = shared / min(commits(A), commits(B)) — the fraction of the
+ * rarer file's commits that also touched the other. Symmetric, in (0,1].
+ */
+export function computeCoupling(commits, opts = {}) {
+    const minShared = opts.minShared ?? 2;
+    const maxFiles = opts.maxFiles ?? 30;
+    const fileCommits = new Map(); // path → # commits touching it
+    const pairShared = new Map(); // "a\x1fb" → # commits touching both
+    for (const c of commits) {
+        const paths = [...new Set(c.files.map((f) => f.path))].filter(Boolean);
+        if (maxFiles > 0 && paths.length > maxFiles)
+            continue; // skip sweeping commits (both counts + pairs)
+        for (const p of paths)
+            fileCommits.set(p, (fileCommits.get(p) ?? 0) + 1);
+        const sorted = paths.slice().sort(); // canonical (a<b) pair keys
+        for (let i = 0; i < sorted.length; i++) {
+            for (let j = i + 1; j < sorted.length; j++) {
+                const key = sorted[i] + US + sorted[j];
+                pairShared.set(key, (pairShared.get(key) ?? 0) + 1);
+            }
+        }
+    }
+    const pairs = [];
+    for (const [key, shared] of pairShared) {
+        if (shared < minShared)
+            continue;
+        const sep = key.indexOf(US);
+        const a = key.slice(0, sep);
+        const b = key.slice(sep + 1);
+        if (opts.focus && a !== opts.focus && b !== opts.focus)
+            continue;
+        const aCommits = fileCommits.get(a) ?? 0;
+        const bCommits = fileCommits.get(b) ?? 0;
+        const denom = Math.min(aCommits, bCommits) || 1;
+        const degree = Math.round((shared / denom) * 100) / 100;
+        pairs.push({ a, b, shared, aCommits, bCommits, degree });
+    }
+    // deterministic: strongest coupling first, then most-shared, then path order
+    pairs.sort((x, y) => y.degree - x.degree ||
+        y.shared - x.shared ||
+        (x.a < y.a ? -1 : x.a > y.a ? 1 : 0) ||
+        (x.b < y.b ? -1 : x.b > y.b ? 1 : 0));
+    return opts.top && opts.top > 0 ? pairs.slice(0, opts.top) : pairs;
+}
+export function couplingToCsv(pairs) {
+    const headers = ['fileA', 'fileB', 'degree', 'shared', 'commitsA', 'commitsB'];
+    const rows = pairs.map((p) => [p.a, p.b, p.degree, p.shared, p.aCommits, p.bCommits]);
+    return toCsv(headers, rows);
+}
+/** Human-readable table. Pure. */
+export function formatCoupling(pairs) {
+    if (pairs.length === 0)
+        return 'no co-change coupling found (raise --since or lower --min-shared)';
+    const lines = [];
+    lines.push('rank  degree  shared  commits(A/B)  files');
+    pairs.forEach((p, i) => {
+        const rank = String(i + 1).padStart(4);
+        const degree = `${Math.round(p.degree * 100)}%`.padStart(6);
+        const shared = String(p.shared).padStart(6);
+        const ab = `${p.aCommits}/${p.bCommits}`.padStart(11);
+        lines.push(`${rank}  ${degree}  ${shared}  ${ab}  ${p.a}  ↔  ${p.b}`);
+    });
+    return lines.join('\n');
+}
+//# sourceMappingURL=coupling.js.map

package/v3/@swarmdo/cli/dist/src/hooks-recipe/command-guard.d.ts

@@ -0,0 +1,46 @@
+/**
+ * command-guard.ts — classify a bash command as safe or blockable, for a
+ * PreToolUse/Bash hook that emits Claude Code's `permissionDecision: "deny"`.
+ *
+ * swarmdo runs headless `claude -p --dangerously-skip-permissions` in its
+ * daemon / worker / repair flows; that flag skips the interactive approval
+ * prompt but NOT hooks, so a PreToolUse deny is the only remaining guardrail.
+ * The denylist is deliberately CONSERVATIVE — it blocks a small set of clearly
+ * destructive / irreversible / remote-exec commands and lets everything else
+ * through, so a routine `rm -rf ./build`, `rm -rf node_modules`, or a
+ * feature-branch force-push is never blocked. Pure + injection-free → fully
+ * unit-tested. This is defense-in-depth, not a sandbox: a determined command
+ * (indirection through a variable, an obscure tool) can still get through.
+ */
+export interface GuardVerdict {
+    block: boolean;
+    /** why it was blocked (present only when block === true) */
+    reason?: string;
+    /** the matched rule id (stable identifier, useful for tests/telemetry) */
+    rule?: string;
+}
+interface Rule {
+    id: string;
+    reason: string;
+    test: (c: string) => boolean;
+}
+/** The denylist. Order determines which reason is reported when several match. */
+export declare const GUARD_RULES: Rule[];
+/** Classify a bash command; blocks on the first matching danger rule, else allows. */
+export declare function classifyCommand(command: string): GuardVerdict;
+/**
+ * Extract the Bash command from a PreToolUse hook payload (the JSON Claude Code
+ * pipes on stdin: `{ "tool_name": "Bash", "tool_input": { "command": "…" } }`).
+ * Tolerant — returns '' when absent or unparseable, so the hook simply allows.
+ */
+export declare function extractBashCommand(payload: string): string;
+/** The PreToolUse deny payload Claude Code honors to hard-block a tool call. */
+export declare function denyOutput(reason: string): {
+    hookSpecificOutput: {
+        hookEventName: 'PreToolUse';
+        permissionDecision: 'deny';
+        permissionDecisionReason: string;
+    };
+};
+export {};
+//# sourceMappingURL=command-guard.d.ts.map

package/v3/@swarmdo/cli/dist/src/hooks-recipe/command-guard.js

@@ -0,0 +1,120 @@
+/**
+ * command-guard.ts — classify a bash command as safe or blockable, for a
+ * PreToolUse/Bash hook that emits Claude Code's `permissionDecision: "deny"`.
+ *
+ * swarmdo runs headless `claude -p --dangerously-skip-permissions` in its
+ * daemon / worker / repair flows; that flag skips the interactive approval
+ * prompt but NOT hooks, so a PreToolUse deny is the only remaining guardrail.
+ * The denylist is deliberately CONSERVATIVE — it blocks a small set of clearly
+ * destructive / irreversible / remote-exec commands and lets everything else
+ * through, so a routine `rm -rf ./build`, `rm -rf node_modules`, or a
+ * feature-branch force-push is never blocked. Pure + injection-free → fully
+ * unit-tested. This is defense-in-depth, not a sandbox: a determined command
+ * (indirection through a variable, an obscure tool) can still get through.
+ */
+/** `rm` invoked with BOTH a recursive and a force flag (combined `-rf`/`-fr` or separate). */
+function isRecursiveForceRm(c) {
+    if (!/\brm\b/.test(c))
+        return false;
+    const recursive = /(?:^|\s)-[a-z]*r[a-z]*(?=\s|$)/i.test(c) || /(?:^|\s)--recursive\b/.test(c);
+    const force = /(?:^|\s)-[a-z]*f[a-z]*(?=\s|$)/i.test(c) || /(?:^|\s)--force\b/.test(c);
+    return recursive && force;
+}
+/** Does the command target a root / home / top-level system path (the only rm targets we block)? */
+function hasCriticalTarget(c) {
+    if (/--no-preserve-root\b/.test(c))
+        return true;
+    // a bare `/`, `~`, `$HOME`/`${HOME}` token, optionally with a trailing `/` or `/*` or `*`
+    if (/(?:^|\s)(?:\/|~|\$\{?HOME\}?)(?:\/\s|\/$|\/\*|\*|\s|$)/.test(c))
+        return true;
+    // a top-level system directory
+    if (/(?:^|\s)\/(?:etc|usr|bin|sbin|var|lib|lib64|boot|sys|proc|dev|root|opt)(?:\/|\s|\*|$)/.test(c))
+        return true;
+    return false;
+}
+/** The denylist. Order determines which reason is reported when several match. */
+export const GUARD_RULES = [
+    {
+        id: 'rm-rf-critical',
+        reason: 'recursive force-delete of a root, home, or system path (rm -rf /, ~, or --no-preserve-root)',
+        test: (c) => isRecursiveForceRm(c) && hasCriticalTarget(c),
+    },
+    {
+        id: 'pipe-to-shell',
+        reason: 'piping remote content straight into a shell (curl/wget … | sh) — remote code execution',
+        test: (c) => /(?:\bcurl\b|\bwget\b)[^|]*\|\s*(?:sudo\s+)?(?:sh|bash|zsh|dash|ksh|fish)\b/.test(c),
+    },
+    {
+        id: 'force-push-protected',
+        reason: 'force-push to a protected branch (main/master) — use --force-with-lease',
+        test: (c) => /\bgit\s+push\b/.test(c) && /(?:--force(?!-with-lease)\b|(?:^|\s)-f\b)/.test(c) && /\b(?:main|master)\b/.test(c),
+    },
+    {
+        id: 'chmod-world-writable',
+        reason: 'world-writable permissions (chmod 777)',
+        test: (c) => /\bchmod\s+(?:-[a-z]+\s+)*(?:0?777|a\+rwx|ugo\+rwx)\b/i.test(c),
+    },
+    {
+        id: 'dd-to-device',
+        reason: 'dd writing directly to a block device (of=/dev/…) — data-destroying',
+        test: (c) => /\bdd\b[^|;&]*\bof=\/dev\/(?:sd|nvme|disk|hd|mmcblk|vd|xvd)/.test(c),
+    },
+    {
+        id: 'mkfs',
+        reason: 'formatting a filesystem (mkfs) — data-destroying',
+        test: (c) => /\bmkfs(?:\.\w+)?\b/.test(c),
+    },
+    {
+        id: 'redirect-to-device',
+        reason: 'redirecting output onto a raw block device (> /dev/sd…) — data-destroying',
+        test: (c) => /(?:^|\s)>{1,2}\s*\/dev\/(?:sd|nvme|disk|hd|mmcblk|vd|xvd)/.test(c),
+    },
+    {
+        id: 'fork-bomb',
+        reason: 'shell fork bomb',
+        test: (c) => /:\(\)\s*\{\s*:\s*\|\s*:\s*&\s*\}\s*;\s*:/.test(c.replace(/\s+/g, ' ')),
+    },
+];
+/** Classify a bash command; blocks on the first matching danger rule, else allows. */
+export function classifyCommand(command) {
+    const c = (command ?? '').trim();
+    if (!c)
+        return { block: false };
+    for (const r of GUARD_RULES) {
+        // a bad regex must never crash the hook (and thus never wrongly block)
+        try {
+            if (r.test(c))
+                return { block: true, reason: r.reason, rule: r.id };
+        }
+        catch { /* skip */ }
+    }
+    return { block: false };
+}
+/**
+ * Extract the Bash command from a PreToolUse hook payload (the JSON Claude Code
+ * pipes on stdin: `{ "tool_name": "Bash", "tool_input": { "command": "…" } }`).
+ * Tolerant — returns '' when absent or unparseable, so the hook simply allows.
+ */
+export function extractBashCommand(payload) {
+    if (!payload || !payload.trim())
+        return '';
+    try {
+        const o = JSON.parse(payload);
+        const cmd = o?.tool_input?.command ?? o?.command;
+        return typeof cmd === 'string' ? cmd : '';
+    }
+    catch {
+        return '';
+    }
+}
+/** The PreToolUse deny payload Claude Code honors to hard-block a tool call. */
+export function denyOutput(reason) {
+    return {
+        hookSpecificOutput: {
+            hookEventName: 'PreToolUse',
+            permissionDecision: 'deny',
+            permissionDecisionReason: reason,
+        },
+    };
+}
+//# sourceMappingURL=command-guard.js.map

package/v3/@swarmdo/cli/dist/src/hooks-recipe/recipe.js

@@ -37,6 +37,14 @@ export const RECIPES = [
         title: 'Surface new cross-session messages each prompt',
         description: 'On every prompt, injects any unread messages other sessions sent to this one (multiplayer swarms) as context, then marks them read — so mail surfaces without polling (UserPromptSubmit hook). Powered by `swarmdo comms inbox --hook`. Opt-in.',
     },
+    {
+        name: 'command-guard',
+        event: 'PreToolUse',
+        matcher: 'Bash',
+        command: 'swarmdo hooks guard-bash',
+        title: 'Block dangerous bash commands before they run',
+        description: 'Inspects every Bash tool call and hard-blocks a conservative denylist of destructive commands (rm -rf / , curl|sh, force-push to main, chmod 777, dd to a device, mkfs, fork bombs) via Claude Code’s PreToolUse `permissionDecision: "deny"`. Powered by `swarmdo hooks guard-bash`. Opt-in — the one guardrail that still fires under `--dangerously-skip-permissions`.',
+    },
 ];
 export function findRecipe(name) {
     const n = (name ?? '').trim().toLowerCase();

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

@@ -26,6 +26,7 @@ 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 { couplingTools } from './mcp-tools/coupling-tools.js';
 import { affectedTools } from './mcp-tools/affected-tools.js';
 import { cyclesTools } from './mcp-tools/cycles-tools.js';
 import { testreportTools } from './mcp-tools/testreport-tools.js';
@@ -119,6 +120,7 @@ const TOOL_GROUPS = {
     license: () => licenseTools,
     apply: () => applyTools,
     hotspots: () => hotspotsTools,
+    coupling: () => couplingTools,
     affected: () => affectedTools,
     cycles: () => cyclesTools,
     testreport: () => testreportTools,

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

@@ -0,0 +1,14 @@
+/**
+ * Coupling MCP Tool
+ *
+ * Let an agent ask "which files change together?" and get ranked JSON — the
+ * EMPIRICAL complement to `affected`'s static import graph. Files that keep
+ * landing in the same commit are coupled in practice even when no import edge
+ * connects them (a JSON schema and its TS type, a serializer/deserializer split
+ * across modules, a doc that must track an API). Surfacing that lets an agent
+ * catch the co-edit it would otherwise forget. Shares the pure engine in
+ * ../coupling/coupling.ts with the CLI; captures git history via subprocess.
+ */
+import type { MCPTool } from './types.js';
+export declare const couplingTools: MCPTool[];
+//# sourceMappingURL=coupling-tools.d.ts.map

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

@@ -0,0 +1,56 @@
+/**
+ * Coupling MCP Tool
+ *
+ * Let an agent ask "which files change together?" and get ranked JSON — the
+ * EMPIRICAL complement to `affected`'s static import graph. Files that keep
+ * landing in the same commit are coupled in practice even when no import edge
+ * connects them (a JSON schema and its TS type, a serializer/deserializer split
+ * across modules, a doc that must track an API). Surfacing that lets an agent
+ * catch the co-edit it would otherwise forget. Shares the pure engine in
+ * ../coupling/coupling.ts with the CLI; captures git history via subprocess.
+ */
+import { execFileSync } from 'node:child_process';
+import { parseGitLog } from '../hotspots/hotspots.js';
+import { computeCoupling } from '../coupling/coupling.js';
+import { normalizeSince } from '../util/since.js';
+const couplingTool = {
+    name: 'coupling',
+    description: 'Rank file pairs that change together in git history (temporal/co-change coupling) — the empirical complement to `affected`. Returns ranked JSON so an agent editing one file can see what else historically moves with it and avoid a forgotten co-edit. Pass `file` for a "what changes with X?" query. Runs in a git repository.',
+    category: 'coupling',
+    tags: ['git', 'co-change', 'coupling', 'impact', 'refactor'],
+    inputSchema: {
+        type: 'object',
+        properties: {
+            path: { type: 'string', description: 'repo path to run in (default cwd)' },
+            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 pairs (default 30; 0 = all)' },
+            minShared: { type: 'number', description: 'drop pairs sharing fewer than N commits (default 2)' },
+            maxFiles: { type: 'number', description: 'skip commits touching more than N files (default 30; 0 = no cap)' },
+            file: { type: 'string', description: 'show only pairs involving this exact path ("what changes with X?")' },
+        },
+    },
+    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 top = typeof params.top === 'number' ? params.top : 30;
+        const minShared = typeof params.minShared === 'number' ? params.minShared : 2;
+        const maxFiles = typeof params.maxFiles === 'number' ? params.maxFiles : 30;
+        const focus = typeof params.file === 'string' && params.file ? params.file : undefined;
+        // Capture the FULL history (no pathspec filter even when focused) — filtering
+        // the log to `focus` would strip the co-changed files out of each commit's
+        // numstat. We filter PAIRS in the engine (opts.focus) instead. Same
+        // `--numstat` dump `hotspots` parses.
+        const args = ['log', '--no-merges', '--numstat', `--since=${normalizeSince(since)}`, '--format=format:%x01%H%x1f%aN%x1f%aI'];
+        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 coupling = computeCoupling(parseGitLog(raw), { minShared, maxFiles, top: top > 0 ? top : undefined, focus });
+        return { since, minShared, count: coupling.length, coupling };
+    },
+};
+export const couplingTools = [couplingTool];
+//# sourceMappingURL=coupling-tools.js.map