swarmdo 1.37.0 → 1.50.0

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.37.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.50.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)
@@ -275,12 +275,12 @@ The recent release train added a full day-to-day operations layer around the swa
 | `swarmdo usage guard` | **Budget policy** — limits for the active 5h block / today / month via flags or `SWARMDO_GUARD_*` env → ok / warn / over; `--strict` exits 1, safe for CI gates and Stop hooks |
 | `swarmdo hud` | **One-screen ops HUD** — 5h block burn, task readiness, daemon workers, memory snapshots (`--watch`, `--json`) |
 | `swarmdo repair` (alias `tdd-repair`) | **Test-Driven Repair** — a bounded, budget-capped headless `claude` loop that fixes source until a failing test passes; dry-run unless `--confirm` |
-| `swarmdo task … --dependencies` | **Task dependency DAG** — `task ready` lists unblocked work, `task graph` renders the graph, the dispatcher gates on readiness; `task parse-prd <spec.md>` decomposes a PRD straight into the DAG |
+| `swarmdo task … --dependencies` | **Task dependency DAG** — `task ready` lists unblocked work, `task graph` renders the graph, the dispatcher gates on readiness; `task parse-prd <spec.md>` decomposes a PRD straight into the DAG; `task doctor` (alias `health`) separates a transient wait from a **permanent stall** — a task whose prerequisite failed/was cancelled/is missing will never run — and flags whole-graph **deadlock**, `--ci` so a dispatch loop can't spin forever (Airflow `upstream_failed` semantics) |
 | `swarmdo worktree` (alias `wt`) | **Parallel-agent isolation** on git worktrees — add / list / diff / merge / remove |
 | `swarmdo transcript` (alias `tx`) | **Export any Claude Code session** to clean markdown — system noise stripped, ready to share; `transcript search <query>` full-text-searches every session |
 | `swarmdo compact` | **Compress noisy command output** before it reaches an LLM — strip ANSI, collapse repeats, fold `node_modules` stack frames, window long logs. `npm test 2>&1 \| swarmdo compact` or `swarmdo compact -- npm test` (exit code propagates). Deterministic, zero tokens |
 | `swarmdo codegraph` (alias `cg`) | **Queryable symbol index** — `codegraph index` scans TS/JS for exported symbols; `query <name>` (with `--fuzzy`/`--kind`) and `file <path>` answer "where is X defined / what does this file export" from `.swarm/codegraph.json` instead of grep+read round-trips. `codegraph importers <file>` shows reverse deps ("what breaks if I change this"); `codegraph imports <file>` shows a file's dependencies. 1,786 symbols + import graph across 296 files in <1s. Also MCP tools (`codegraph_query`/`file`/`imports`/`importers`/`index`/`stats`) so agents query the graph in-session |
-| `swarmdo redact` | **Mask secrets before they reach an LLM/log/memory** — detect API keys, tokens, and private keys (gitleaks-style rule catalog + Shannon-entropy fallback) and redact them. Stdin filter (`cat deploy.log \| swarmdo redact`), command-wrap (`swarmdo redact -- npm run deploy`), or `--scan` to fail CI on any secret. Also MCP tools (`redact_text`/`redact_scan`). Deterministic, zero tokens |
+| `swarmdo redact` | **Mask secrets before they reach an LLM/log/memory** — detect API keys, tokens, and private keys (gitleaks-style rule catalog + Shannon-entropy fallback) and redact them. Stdin filter (`cat deploy.log \| swarmdo redact`), command-wrap (`swarmdo redact -- npm run deploy`), or `--scan` to fail CI on any secret — `--scan --sarif` emits a **SARIF 2.1.0** report so leaked secrets surface as GitHub code-scanning alerts + PR annotations. Also MCP tools (`redact_text`/`redact_scan`). Deterministic, zero tokens |
 | `swarmdo pack` | **Bundle a repo into one AI-context blob** — walk the tree (respects `.gitignore` + glob `--include`/`--exclude`, skips binaries/node_modules), emit markdown/xml/json/plain with a directory tree and per-file + total token estimates. `swarmdo pack --tokens` for a budget breakdown; `--redact` masks secrets first. Deterministic |
 | `swarmdo env` | **Catch env-var drift before deploy** — statically scan code for `process.env.X` / `import.meta.env.X` / `Deno.env.get` / `os.getenv` references and reconcile against `.env` and `.env.example`: reports **missing** (used but undeclared), **unused**, and **undocumented**. `--ci` exits 1 on missing vars. Also an MCP tool (`env_check`). Deterministic |
 | `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 |
@@ -289,16 +289,20 @@ The recent release train added a full day-to-day operations layer around the swa
 | `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 affected` | **Run only the tests your change touches** — from a git diff, walk `codegraph`'s import graph to list every file (and test file) a change could break (reverse-dependency closure, nx/turbo/`jest --findRelatedTests` style). `--base main`, `--tests` (pipeable list), `--format json`. Also an MCP tool (`affected`). Deterministic |
 | `swarmdo cycles` | **Find circular import dependencies** — an SCC scan over `codegraph`'s import graph surfaces the mutually-importing file groups (and self-imports) that cause temporal-dead-zone and `undefined`-export bugs, `madge --circular` style. `--ci` exits 1 on any cycle to gate a build; `--format json`. Also an MCP tool (`cycles`). Deterministic |
+| `swarmdo coupling` | **Files that change together** — the empirical complement to `affected`'s static import graph: mine git history for file pairs that keep landing in the same commit (a schema and its type, a serializer split across modules) so you catch the co-edit you'd otherwise forget. `--file <path>` answers "what changes with X?", `--since`, `--min-shared`, `--csv`. Modeled on code-maat / CodeScene. Also an MCP tool (`coupling`). Deterministic |
+| `swarmdo ownership` | **Who owns each file, and what breaks if they leave** — a per-file knowledge map + bus factor from git history: the dominant author, ownership concentration, and the fewest authors whose churn clears 50% (a lone owner is flagged ⚠ key-person), plus a repo-wide truck factor. `--since`, `--min-churn`, `--top`, `--csv`, `--format json`. code-maat main-dev / CodeScene "Knowledge Map"; also an MCP tool (`ownership`). Deterministic |
+| `swarmdo hidden-coupling` | **Co-change with no import edge** — join the two graphs swarmdo already owns (temporal `coupling` from git + `codegraph`'s import graph) and emit the set difference: file pairs that keep changing together yet nothing in the code links them ("logical minus structural coupling" — a config and its consumers, a schema and its mirror type). The co-edit `affected` can't see. `--since`, `--min-shared`, `--csv`, `--format json`. Grounded in Gall et al. (ICSM 1998). Deterministic |
 | `swarmdo testreport` | **JUnit/TAP → failure digest** — turn raw test-result files into the exact failing test names + `file:line` + assertion messages, instead of scanning hundreds of log lines. The front-half of the test→fix loop: feed the failures straight into `repair`. Reads a file, a directory, or stdin; `--ci` exits 1 on any failure, `--format json`. Also an MCP tool (`testreport`). 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` |
+| `swarmdo changelog` (alias `notes`) | **Release notes from conventional commits** — `--out NOTES.md` feeds `gh release create --notes-file`; `--contributors` appends a credited contributor roll |
 | `swarmdo mcp doctor` | **MCP config diagnosis** — missing binaries, bad URLs, malformed entries across `.mcp.json` + `~/.claude.json` |
+| `swarmdo config lint` | **Static config validation** — the pure shape layer for `swarmdo.config.json`, the `.claude/settings*.json` hooks block, `.mcp.json`, **`.claude/agents/*.md` subagents** (missing `name`/`description`, a `name` duplicated across files — CC silently loads only one — a bad `model`, malformed frontmatter), and **custom slash commands + skills** (malformed YAML that makes CC load empty metadata, a bad `effort`, an inline `` !`cmd` `` bash-injection that's inert or not covered by `allowed-tools`). `--strict` gates CI |
 | `swarmdo permissions` (alias `perms`) | **Audit your Claude Code permission rules** — static analysis of `permissions.allow`/`deny`/`ask` in `.claude/settings*.json`: flags allow↔deny conflicts (dead rules), over-broad `Bash(*)` grants, shadowed/redundant rules, duplicates, and malformed entries. `--strict` gates CI. Read-only; the static-safety sibling of `config lint` / `mcp doctor` |
 | `swarmdo comms` (alias `mailbox`) | **Cross-session agent mailbox** — one Claude Code session messages another by name (`send -t <session>`, `-t all` broadcasts, `inbox`, `read`, `watch`); sessions on the same repo share `.swarmdo/comms/`. `inbox --hook` surfaces new mail as prompt context without polling. Also MCP tools (`comms_send`/`comms_inbox`) |
 | `swarmdo hooks memory-inject` | **Prompt-time semantic memory injection** — embeds each prompt, vector-searches your stored memories, and injects the most relevant under a token budget (recall at the moment of need); wire it with `hooks recipe memory-inject` |
 | `swarmdo hooks notify -d` | **Desktop notifications** — OS-native toast (macOS `osascript`, Linux `notify-send`) |
-| `swarmdo hooks recipe` | **One-command Claude Code hooks** — install `notify-done`/`notify-input` (desktop pings), `memory-inject` (relevant memories each prompt), or `comms-inbox` (new mail as context); dry-run by default, idempotent merge that never clobbers your settings |
+| `swarmdo hooks recipe` | **One-command Claude Code hooks** — install `notify-done`/`notify-input` (desktop pings), `memory-inject` (relevant memories each prompt), `comms-inbox` (new mail as context), or `command-guard` (a PreToolUse deny hook that blocks dangerous bash — `rm -rf /`, pipe-to-shell, force-push to main — the net swarmdo needs when running headless); dry-run by default, idempotent merge that never clobbers your settings |
 | `swarmdo preset` + `init --preset` | **5-tier capability ladder** — `minimal` → `basic`★ → `standard` → `advanced` → `max`; one word instead of dozens of flags |
 | `swarmdo memory export/import -f obsidian` | **Obsidian vault roundtrip** — DB → markdown notes (YAML frontmatter, `[[wikilinks]]` stay live) → edit in Obsidian → sync back, re-embedded; `import --watch` keeps the vault live-synced as you edit |
 | `swarmdo memory backup` / `revectorize` | WAL-safe nightly DB snapshots · repair hash-era vectors |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "swarmdo",
-  "version": "1.37.0",
+  "version": "1.50.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/apply/apply.js

@@ -150,7 +150,12 @@ export function applyPatch(source, patch, opts = {}) {
     let eofNoEol;
     for (const hunk of patch.hunks) {
         const { oldBlock, newBlock } = hunkBlocks(hunk);
-        const expected = hunk.oldStart - 1 + offset;
+        // For a hunk with old lines, oldStart is 1-based → 0-based is oldStart-1.
+        // But a pure INSERTION uses `@@ -L,0 +M @@` where L is the line AFTER which
+        // to insert (what `diff -U0` emits), so the splice index is L (= oldStart),
+        // not L-1 — otherwise every zero-context insertion lands one line too early
+        // and still reports applied:true (silent corruption). (#91)
+        const expected = hunk.oldStart - (oldBlock.length === 0 ? 0 : 1) + offset;
         // Try the full block, then progressively trim up to `fuzz` context lines
         // off each end (patch fuzz) to tolerate drift.
         let placed = -1;

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

@@ -57,4 +57,25 @@ export declare function lastTag(git: GitRunner): string | null;
 export declare function repoUrlFromGit(git: GitRunner): string | null;
 /** Read + parse commits in a range (e.g. "v1.3.0..HEAD"). */
 export declare function collectCommits(range: string, git: GitRunner): ParsedCommit[];
+export interface Contributor {
+    name: string;
+    handle: string | null;
+}
+/**
+ * GitHub no-reply author emails encode the account login:
+ *   `<id>+<login>@users.noreply.github.com`  (current form)
+ *   `<login>@users.noreply.github.com`        (legacy form)
+ * Return the @handle when the email is one of those, else null.
+ */
+export declare function githubHandle(email: string): string | null;
+/**
+ * Distinct commit authors in a range, oldest-first (git log is newest-first, so
+ * we reverse — the earliest contributor to the range leads). Deduped by author
+ * name (case-insensitive); the GitHub @handle is carried when the author email
+ * is a github no-reply address (back-filled if any of an author's commits has one).
+ * Pure but for the injected git read, mirroring collectCommits.
+ */
+export declare function collectContributors(range: string, git: GitRunner): Contributor[];
+/** Render the `### Contributors` section (empty string when there are none). */
+export declare function renderContributors(contributors: Contributor[]): string;
 //# sourceMappingURL=changelog.d.ts.map

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

@@ -161,4 +161,47 @@ export function collectCommits(range, git) {
     const raw = git(['log', range, '--no-merges', '--pretty=format:%h%x1f%s%x1f%b%x1e']);
     return parseGitLog(raw);
 }
+/**
+ * GitHub no-reply author emails encode the account login:
+ *   `<id>+<login>@users.noreply.github.com`  (current form)
+ *   `<login>@users.noreply.github.com`        (legacy form)
+ * Return the @handle when the email is one of those, else null.
+ */
+export function githubHandle(email) {
+    const m = /^(?:\d+\+)?([A-Za-z0-9](?:[A-Za-z0-9-]*[A-Za-z0-9])?)@users\.noreply\.github\.com$/.exec(email.trim());
+    return m ? m[1] : null;
+}
+/**
+ * Distinct commit authors in a range, oldest-first (git log is newest-first, so
+ * we reverse — the earliest contributor to the range leads). Deduped by author
+ * name (case-insensitive); the GitHub @handle is carried when the author email
+ * is a github no-reply address (back-filled if any of an author's commits has one).
+ * Pure but for the injected git read, mirroring collectCommits.
+ */
+export function collectContributors(range, git) {
+    const raw = git(['log', range, '--no-merges', '--format=%aN%x1f%aE']);
+    const seen = new Map();
+    const lines = raw.split('\n').map((l) => l.trim()).filter(Boolean);
+    for (const line of lines.reverse()) {
+        const [name, email = ''] = line.split('\x1f');
+        if (!name)
+            continue;
+        const key = name.toLowerCase();
+        const existing = seen.get(key);
+        if (existing) {
+            if (!existing.handle)
+                existing.handle = githubHandle(email); // back-fill
+            continue;
+        }
+        seen.set(key, { name, handle: githubHandle(email) });
+    }
+    return [...seen.values()];
+}
+/** Render the `### Contributors` section (empty string when there are none). */
+export function renderContributors(contributors) {
+    if (!contributors.length)
+        return '';
+    const items = contributors.map((c) => (c.handle ? `- ${c.name} (@${c.handle})` : `- ${c.name}`));
+    return ['### Contributors', '', ...items, ''].join('\n');
+}
 //# sourceMappingURL=changelog.js.map

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

@@ -10,7 +10,7 @@
  */
 import * as fs from 'node:fs';
 import { output } from '../output.js';
-import { makeGitRunner, lastTag, repoUrlFromGit, collectCommits, renderChangelog, } from '../changelog/changelog.js';
+import { makeGitRunner, lastTag, repoUrlFromGit, collectCommits, collectContributors, renderChangelog, renderContributors, } from '../changelog/changelog.js';
 function isRepo(git) {
     try {
         git(['rev-parse', '--git-dir']);
@@ -32,6 +32,7 @@ export const changelogCommand = {
         { name: 'out', short: 'o', type: 'string', description: 'write to this file instead of stdout' },
         { name: 'all', short: 'a', type: 'boolean', description: 'include chore/test/ci/build/style + non-conventional commits', default: false },
         { name: 'no-links', type: 'boolean', description: 'omit GitHub commit links', default: false },
+        { name: 'contributors', short: 'c', type: 'boolean', description: 'append a ### Contributors section (commit authors in the range)', default: false },
         { name: 'date', type: 'string', description: 'override the date shown in the title (default: today)' },
     ],
     examples: [
@@ -65,7 +66,17 @@ export const changelogCommand = {
         const repoUrl = ctx.flags['no-links'] === true ? undefined : (repoUrlFromGit(git) ?? undefined);
         const date = ctx.flags.date || new Date().toISOString().slice(0, 10);
         const version = ctx.flags.version || range;
-        const md = renderChangelog(commits, { version, date, repoUrl, includeAll: ctx.flags.all === true });
+        let md = renderChangelog(commits, { version, date, repoUrl, includeAll: ctx.flags.all === true });
+        // Opt-in `### Contributors` section — a separate git read over the SAME range,
+        // so the notes credit everyone whose commits shipped in the release.
+        let contributors = 0;
+        if (ctx.flags.contributors === true) {
+            const people = collectContributors(range, git);
+            contributors = people.length;
+            const section = renderContributors(people);
+            if (section)
+                md = `${md.replace(/\n+$/, '\n')}\n${section}`;
+        }
         const outFile = ctx.flags.out;
         if (outFile) {
             try {
@@ -76,10 +87,10 @@ export const changelogCommand = {
                 return { success: false, exitCode: 1 };
             }
             output.printSuccess(`Wrote ${commits.length} commit(s) of release notes → ${outFile}`);
-            return { success: true, data: { file: outFile, commits: commits.length, range } };
+            return { success: true, data: { file: outFile, commits: commits.length, range, contributors } };
         }
         output.writeln(md);
-        return { success: true, data: { commits: commits.length, range } };
+        return { success: true, data: { commits: commits.length, range, contributors } };
     },
 };
 export default changelogCommand;

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

@@ -400,7 +400,7 @@ const importCommand = {
 const lintCommand = {
     name: 'lint',
     aliases: ['validate'],
-    description: 'Statically validate swarmdo.config.json, .claude/settings*.json hooks, .mcp.json, and the post-1.4 sDo layout',
+    description: 'Statically validate swarmdo.config.json, .claude/settings*.json hooks, .mcp.json, .claude/agents/*.md subagents, .claude/commands + skills slash-command frontmatter/body, and the post-1.4 sDo layout',
     options: [
         { name: 'json', type: 'boolean', description: 'machine-readable findings', default: false },
         { name: 'strict', type: 'boolean', description: 'exit 1 on warnings too (default: errors only)', default: false },
@@ -433,6 +433,39 @@ const lintCommand = {
         const configRel = process.env.SWARMDO_CONFIG && !path.isAbsolute(process.env.SWARMDO_CONFIG)
             ? process.env.SWARMDO_CONFIG.replace(/^\.\//, '')
             : 'swarmdo.config.json';
+        const agentFiles = list('.claude/agents')
+            .filter((n) => n.endsWith('.md'))
+            .map((n) => read(`.claude/agents/${n}`))
+            .filter((x) => x.raw !== null);
+        // Custom slash commands nest (e.g. `.claude/commands/sDo/*.md`), so walk the
+        // tree; skills live one dir deep as `.claude/skills/<name>/SKILL.md`.
+        const walkMd = (rel) => {
+            const acc = [];
+            let entries;
+            try {
+                entries = fs.readdirSync(path.join(cwd, rel), { withFileTypes: true });
+            }
+            catch {
+                return acc;
+            }
+            for (const e of entries) {
+                if (e.name.startsWith('.'))
+                    continue;
+                const childRel = `${rel}/${e.name}`;
+                if (e.isDirectory())
+                    acc.push(...walkMd(childRel));
+                else if (e.isFile() && e.name.endsWith('.md')) {
+                    const r = read(childRel);
+                    if (r.raw !== null)
+                        acc.push({ file: childRel, raw: r.raw });
+                }
+            }
+            return acc;
+        };
+        const commandFiles = walkMd('.claude/commands');
+        const skillFiles = list('.claude/skills')
+            .map((dir) => read(`.claude/skills/${dir}/SKILL.md`))
+            .filter((x) => x.raw !== null);
         const report = lintAll({
             swarmdoConfig: read(configRel),
             settingsFiles: [read('.claude/settings.json'), read('.claude/settings.local.json')],
@@ -440,6 +473,9 @@ const lintCommand = {
             commandsRoot: list('.claude/commands'),
             sdoCommands: list('.claude/commands/sDo'),
             skills: list('.claude/skills'),
+            agentFiles,
+            commandFiles,
+            skillFiles,
         });
         const failed = report.errors > 0 || (ctx.flags.strict === true && report.warnings > 0);
         if (ctx.flags.json === true) {

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

@@ -0,0 +1,17 @@
+/**
+ * `swarmdo coupling` — temporal (co-change) coupling mined from git history.
+ *
+ *   swarmdo coupling                          # top co-changing file pairs
+ *   swarmdo coupling --since 90d --min-shared 3
+ *   swarmdo coupling --file src/auth.ts       # what changes WITH auth.ts?
+ *   swarmdo coupling --format json | --csv
+ *
+ * The EMPIRICAL complement to `affected` (which walks the static import graph):
+ * files that keep landing in the same commit are coupled in practice even with
+ * no import edge. Engine (../coupling/coupling.ts) is pure + tested; this
+ * captures the git log (the same `--numstat` dump `hotspots` uses).
+ */
+import type { Command } from '../types.js';
+export declare const couplingCommand: Command;
+export default couplingCommand;
+//# sourceMappingURL=coupling.d.ts.map

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

@@ -0,0 +1,85 @@
+/**
+ * `swarmdo coupling` — temporal (co-change) coupling mined from git history.
+ *
+ *   swarmdo coupling                          # top co-changing file pairs
+ *   swarmdo coupling --since 90d --min-shared 3
+ *   swarmdo coupling --file src/auth.ts       # what changes WITH auth.ts?
+ *   swarmdo coupling --format json | --csv
+ *
+ * The EMPIRICAL complement to `affected` (which walks the static import graph):
+ * files that keep landing in the same commit are coupled in practice even with
+ * no import edge. Engine (../coupling/coupling.ts) is pure + tested; this
+ * captures the git log (the same `--numstat` dump `hotspots` uses).
+ */
+import { execFileSync } from 'node:child_process';
+import { output } from '../output.js';
+import { parseGitLog } from '../hotspots/hotspots.js';
+import { computeCoupling, formatCoupling, couplingToCsv } from '../coupling/coupling.js';
+import { normalizeSince } from '../util/since.js';
+/** 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 since = typeof ctx.flags.since === 'string' ? ctx.flags.since : '1 year ago';
+    const top = numFlag(ctx.flags.top, 30);
+    const minShared = numFlag(ctx.flags['min-shared'], 2);
+    const maxFiles = numFlag(ctx.flags['max-files'], 30);
+    const focus = typeof ctx.flags.file === 'string' ? ctx.flags.file : (ctx.args[0] || undefined);
+    const asJson = ctx.flags.format === 'json';
+    const asCsv = ctx.flags.csv === true;
+    // NOTE: unlike `hotspots`, we do NOT pathspec-filter the log to `focus` — that
+    // would strip the co-changed files out of each commit's numstat. We capture
+    // the full history and filter PAIRS in the engine (opts.focus) instead.
+    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: 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 pairs = computeCoupling(parseGitLog(raw), {
+        minShared,
+        maxFiles,
+        top: top > 0 ? top : undefined,
+        focus,
+    });
+    if (asCsv) {
+        process.stdout.write(couplingToCsv(pairs) + '\n');
+    }
+    else if (asJson) {
+        process.stdout.write(JSON.stringify({ generated: new Date().toISOString(), since, minShared, count: pairs.length, coupling: pairs }, null, 2) + '\n');
+    }
+    else if (pairs.length === 0) {
+        output.writeln(output.dim(`no co-change coupling found${focus ? ` for ${focus}` : ''} — raise --since or lower --min-shared`));
+    }
+    else {
+        output.writeln(output.bold(`Co-change coupling${focus ? ` for ${focus}` : ''} (since ${since}, min-shared ${minShared})`));
+        output.writeln(formatCoupling(pairs));
+    }
+    return { success: true, exitCode: 0 };
+}
+export const couplingCommand = {
+    name: 'coupling',
+    description: 'Rank file pairs that change together in git history (temporal/co-change coupling) — the empirical complement to `affected`',
+    options: [
+        { name: 'since', description: 'history window, e.g. 90d or "3 months ago" (default 1 year)', type: 'string' },
+        { name: 'min-shared', description: 'drop pairs sharing fewer than N commits (default 2)', type: 'string' },
+        { name: 'max-files', description: 'skip commits touching more than N files (default 30; 0 = no cap)', type: 'string' },
+        { name: 'file', description: 'show only pairs involving this path ("what changes with X?")', type: 'string' },
+        { name: 'top', description: 'keep only the top N pairs (default 30; 0 = all)', type: 'string' },
+        { name: 'csv', description: 'export the ranking as CSV (for spreadsheets)', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'swarmdo coupling --since 6mo --min-shared 3', description: 'Strongly co-changing pairs in the last 6 months' },
+        { command: 'swarmdo coupling --file src/auth.ts', description: 'What tends to change together with auth.ts?' },
+        { command: 'swarmdo coupling --csv > coupling.csv', description: 'Export the coupling ranking to CSV' },
+    ],
+    action: run,
+};
+export default couplingCommand;
+//# sourceMappingURL=coupling.js.map

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

@@ -0,0 +1,19 @@
+/**
+ * `swarmdo hidden-coupling` — files that CHANGE TOGETHER but have no import edge.
+ *
+ *   swarmdo hidden-coupling                       # co-change pairs the code doesn't explain
+ *   swarmdo hidden-coupling --since 6mo --min-shared 3
+ *   swarmdo hidden-coupling --format json | --csv
+ *
+ * "Logical coupling minus structural coupling": pairs with a high co-change
+ * `degree` (from `coupling`) yet NO import edge connecting them (from
+ * `codegraph`). A dependency real enough to move two files in lockstep but
+ * invisible in the code — the co-edit an agent following imports would miss, or
+ * a missing abstraction a reviewer should question. Composes the two capture
+ * paths verbatim: git-log + `computeCoupling`, and the codegraph index load.
+ * Engine (../coupling/hidden.ts) is pure + tested.
+ */
+import type { Command } from '../types.js';
+export declare const hiddenCouplingCommand: Command;
+export default hiddenCouplingCommand;
+//# sourceMappingURL=hidden-coupling.d.ts.map

package/v3/@swarmdo/cli/dist/src/commands/hidden-coupling.js

@@ -0,0 +1,92 @@
+/**
+ * `swarmdo hidden-coupling` — files that CHANGE TOGETHER but have no import edge.
+ *
+ *   swarmdo hidden-coupling                       # co-change pairs the code doesn't explain
+ *   swarmdo hidden-coupling --since 6mo --min-shared 3
+ *   swarmdo hidden-coupling --format json | --csv
+ *
+ * "Logical coupling minus structural coupling": pairs with a high co-change
+ * `degree` (from `coupling`) yet NO import edge connecting them (from
+ * `codegraph`). A dependency real enough to move two files in lockstep but
+ * invisible in the code — the co-edit an agent following imports would miss, or
+ * a missing abstraction a reviewer should question. Composes the two capture
+ * paths verbatim: git-log + `computeCoupling`, and the codegraph index load.
+ * Engine (../coupling/hidden.ts) is pure + tested.
+ */
+import { execFileSync } from 'node:child_process';
+import { output } from '../output.js';
+import { parseGitLog } from '../hotspots/hotspots.js';
+import { computeCoupling } from '../coupling/coupling.js';
+import { computeHiddenCoupling, formatHiddenCoupling, hiddenCouplingToCsv } from '../coupling/hidden.js';
+import { loadIndex, scanRepo, saveIndex } from '../codegraph/store.js';
+import { normalizeSince } from '../util/since.js';
+/** 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 since = typeof ctx.flags.since === 'string' ? ctx.flags.since : '1 year ago';
+    const top = numFlag(ctx.flags.top, 30);
+    const minShared = numFlag(ctx.flags['min-shared'], 2);
+    const maxFiles = numFlag(ctx.flags['max-files'], 30);
+    const asJson = ctx.flags.format === 'json';
+    const asCsv = ctx.flags.csv === true;
+    // Capture 1: the full co-change history (same `--numstat` dump `coupling` uses;
+    // NO pathspec filter — that would strip co-changed files from each commit).
+    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: 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 };
+    }
+    // Rank ALL coupling pairs (no top yet — we cap the HIDDEN set after filtering).
+    const pairs = computeCoupling(parseGitLog(raw), { minShared, maxFiles });
+    // Capture 2: the static import graph (prefer a saved index; build one if absent).
+    let index = loadIndex(root);
+    if (!index) {
+        index = scanRepo(root);
+        try {
+            saveIndex(root, index);
+        }
+        catch { /* read-only fs — in-memory is fine */ }
+    }
+    const hidden = computeHiddenCoupling(pairs, index.imports, { top: top > 0 ? top : undefined });
+    if (asCsv) {
+        process.stdout.write(hiddenCouplingToCsv(hidden) + '\n');
+    }
+    else if (asJson) {
+        process.stdout.write(JSON.stringify({ generated: new Date().toISOString(), since, minShared, coupled: pairs.length, count: hidden.length, hidden }, null, 2) + '\n');
+    }
+    else if (hidden.length === 0) {
+        output.writeln(output.dim(`no hidden coupling found — every co-change pair has an import edge (or none met --min-shared ${minShared} / --since ${since})`));
+    }
+    else {
+        output.writeln(output.bold(`Hidden coupling (co-change with NO import edge, since ${since}, min-shared ${minShared})`));
+        output.writeln(formatHiddenCoupling(hidden));
+        output.writeln(output.dim(`${hidden.length} hidden of ${pairs.length} coupled pair(s) — these move together but nothing in the code links them`));
+    }
+    return { success: true, exitCode: 0 };
+}
+export const hiddenCouplingCommand = {
+    name: 'hidden-coupling',
+    description: 'Rank file pairs that change together in git history but have NO import edge (logical minus structural coupling) — the co-edit `affected` can\'t see',
+    options: [
+        { name: 'since', description: 'history window, e.g. 90d or "3 months ago" (default 1 year)', type: 'string' },
+        { name: 'min-shared', description: 'drop pairs sharing fewer than N commits (default 2)', type: 'string' },
+        { name: 'max-files', description: 'skip commits touching more than N files (default 30; 0 = no cap)', type: 'string' },
+        { name: 'top', description: 'keep only the top N hidden pairs (default 30; 0 = all)', type: 'string' },
+        { name: 'csv', description: 'export the ranking as CSV (for spreadsheets)', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'swarmdo hidden-coupling --since 6mo --min-shared 3', description: 'Strong co-change pairs with no code link, last 6 months' },
+        { command: 'swarmdo hidden-coupling --format json', description: 'Machine-readable hidden-coupling report' },
+    ],
+    action: run,
+};
+export default hiddenCouplingCommand;
+//# sourceMappingURL=hidden-coupling.js.map

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

@@ -10,6 +10,7 @@ import { existsSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 import { bridgeSearchEntries } from '../memory/memory-bridge.js';
 import { selectInjectionMemories, mapSearchResultsToCandidates, extractPromptFromPayload, } from '../memory-inject/select.js';
+import { classifyCommand, extractBashCommand, denyOutput } from '../hooks-recipe/command-guard.js';
 /**
  * #1686 — `?? 0` only defaults null/undefined; NaN slips through and
  * surfaces as `"NaN"` (or earlier crashed `.toFixed`) in the metrics
@@ -849,6 +850,58 @@ const memoryInjectCommand = {
         }
     },
 };
+/**
+ * guard-bash — the #83 PreToolUse/Bash guardrail. Reads the hook payload from
+ * stdin (or --command), classifies the bash command against a conservative
+ * destructive-command denylist, and on a match emits Claude Code's
+ * `permissionDecision: "deny"` to hard-block it. This is the only safety net
+ * that still fires under headless `claude -p --dangerously-skip-permissions`.
+ * Hook-safe: it NEVER errors and stays silent (allow) for anything not on the
+ * denylist, so it can't break a legitimate command.
+ */
+const guardBashCommand = {
+    name: 'guard-bash',
+    description: 'Block dangerous bash commands (PreToolUse hook): emits permissionDecision:deny on a destructive-command denylist',
+    options: [
+        { name: 'command', short: 'c', description: 'Command to classify (else read the hook JSON from stdin)', type: 'string' },
+        { name: 'preview', description: 'Print the human-readable verdict instead of emitting hook JSON', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'swarmdo hooks guard-bash -c "rm -rf /" --preview', description: 'Check whether a command would be blocked' },
+        { command: 'echo \'{"tool_input":{"command":"rm -rf /"}}\' | swarmdo hooks guard-bash', description: 'Run as a PreToolUse/Bash hook' },
+    ],
+    action: async (ctx) => {
+        const preview = Boolean(ctx.flags.preview);
+        // A hook must NEVER break a tool call by crashing: swallow everything, default to allow.
+        try {
+            if (process.env.SWARMDO_GUARD_BASH_DISABLE === '1')
+                return { success: true };
+            let command = (ctx.flags.command || ctx.args.join(' ')).trim();
+            if (!command)
+                command = extractBashCommand(await readHookStdin());
+            if (!command)
+                return { success: true }; // nothing to classify → allow
+            const verdict = classifyCommand(command);
+            if (preview) {
+                if (verdict.block)
+                    output.printError(`BLOCK: ${verdict.reason} [${verdict.rule}]`);
+                else
+                    output.printSuccess('allow — no destructive pattern matched');
+                return { success: true, data: verdict };
+            }
+            // Hook mode: emit the deny JSON only on a block; silence = allow.
+            if (verdict.block) {
+                process.stdout.write(JSON.stringify(denyOutput(verdict.reason)) + '\n');
+            }
+            return { success: true };
+        }
+        catch (err) {
+            if (preview)
+                output.printError(`guard-bash failed: ${String(err)}`);
+            return { success: true }; // never fail the hook (fail-open: a broken guard must not block work)
+        }
+    },
+};
 // Explain subcommand
 const explainCommand = {
     name: 'explain',
@@ -4672,6 +4725,7 @@ export const hooksCommand = {
         sessionRestoreCommand,
         routeCommand,
         memoryInjectCommand,
+        guardBashCommand,
         explainCommand,
         pretrainCommand,
         buildAgentsCommand,
@@ -4730,6 +4784,7 @@ export const hooksCommand = {
             `${output.highlight('session-restore')} - Restore a previous session`,
             `${output.highlight('route')}           - Route tasks to optimal agents`,
             `${output.highlight('memory-inject')}   - Inject relevant memories into the prompt (UserPromptSubmit)`,
+            `${output.highlight('guard-bash')}      - Block dangerous bash commands (PreToolUse deny)`,
             `${output.highlight('explain')}         - Explain routing decisions`,
             `${output.highlight('pretrain')}        - Bootstrap intelligence from repository`,
             `${output.highlight('build-agents')}    - Generate optimized agent configs`,

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

@@ -14,6 +14,7 @@
 import { execFileSync } from 'node:child_process';
 import { output } from '../output.js';
 import { parseGitLog, computeHotspots, formatHotspots, hotspotsToCsv } from '../hotspots/hotspots.js';
+import { normalizeSince } from '../util/since.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) {
@@ -38,7 +39,7 @@ async function run(ctx) {
     // `%an`) resolves author names through `.mailmap`, so name/email variants of
     // the same person fold into one identity — otherwise the author-spread factor
     // in the risk score is silently inflated. Identical to `%an` when no .mailmap.
-    const args = ['log', '--no-merges', '--numstat', `--since=${since}`, '--format=format:%x01%H%x1f%aN%x1f%aI'];
+    const args = ['log', '--no-merges', '--numstat', `--since=${normalizeSince(since)}`, '--format=format:%x01%H%x1f%aN%x1f%aI'];
     if (pathArg)
         args.push('--', pathArg);
     let raw;

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

@@ -51,6 +51,15 @@ const commandLoaders = {
     // Circular-import detector (madge --circular demand) — SCC scan over
     // codegraph's import graph; catches TDZ/undefined-export bugs.
     cycles: () => import('./cycles.js'),
+    // Temporal (co-change) coupling from git history (code-maat demand) — file
+    // pairs that change together; the empirical complement to `affected`.
+    coupling: () => import('./coupling.js'),
+    // Per-file knowledge map + bus factor from git history (code-maat main-dev
+    // demand) — who owns each file, and what breaks if they leave.
+    ownership: () => import('./ownership.js'),
+    // Hidden coupling — co-change pairs with NO import edge (logical minus
+    // structural coupling); joins `coupling`'s git capture with codegraph's graph.
+    'hidden-coupling': () => import('./hidden-coupling.js'),
     // JUnit/TAP test-result parser (dorny/test-reporter demand) — raw results →
     // failing test + file:line + message; the front-half of the test→fix loop.
     testreport: () => import('./testreport.js'),
@@ -293,7 +302,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, hotspotsCmd, affectedCmd, cyclesCmd, testreportCmd, compactSnapshotCmd,] = 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, affectedCmd, cyclesCmd, couplingCmd, ownershipCmd, hiddenCouplingCmd, testreportCmd, compactSnapshotCmd,] = 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'),
@@ -301,7 +310,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('hotspots'), loadCommand('affected'), loadCommand('cycles'), loadCommand('testreport'), loadCommand('compact-snapshot'),
+        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'), loadCommand('affected'), loadCommand('cycles'), loadCommand('coupling'), loadCommand('ownership'), loadCommand('hidden-coupling'), loadCommand('testreport'), loadCommand('compact-snapshot'),
     ]);
     return {
         primary: [
@@ -317,7 +326,7 @@ export async function getCommandsByCategory() {
         utility: [
             configCmd, doctorCmd, daemonCmd, completionsCmd,
             migrateCmd, workflowCmd, demoCmd,
-            statuslineCmd, compressCmd, compactCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, affectedCmd, cyclesCmd, testreportCmd, compactSnapshotCmd, efficiencyCmd,
+            statuslineCmd, compressCmd, compactCmd, redactCmd, packCmd, envCmd, licenseCmd, sbomCmd, applyCmd, hotspotsCmd, affectedCmd, cyclesCmd, couplingCmd, ownershipCmd, hiddenCouplingCmd, testreportCmd, compactSnapshotCmd, efficiencyCmd,
         ].filter(Boolean),
         analysis: [
             analyzeCmd, routeCmd, progressCmd, usageCmd, hudCmd, codegraphCmd,