swarmdo 1.37.0 → 1.50.0

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

@@ -0,0 +1,18 @@
+/**
+ * `swarmdo ownership` — per-file knowledge map + BUS FACTOR mined from git history.
+ *
+ *   swarmdo ownership                      # knowledge map, most fragile files first
+ *   swarmdo ownership src --since 90d       # scope to a path + window
+ *   swarmdo ownership --top 10 --format json
+ *   swarmdo ownership --csv > ownership.csv
+ *
+ * "Who owns each file, and what breaks if they leave?" — the code-maat
+ * main-dev / bus-factor analysis. Files where one author owns nearly all the
+ * churn (bus factor 1) are key-person risks. Pairs with `hotspots` (change-risk)
+ * and `coupling` (co-change). Engine (../ownership/ownership.ts) is pure +
+ * tested; this captures the git log (the same `--numstat` dump those use).
+ */
+import type { Command } from '../types.js';
+export declare const ownershipCommand: Command;
+export default ownershipCommand;
+//# sourceMappingURL=ownership.d.ts.map

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

@@ -0,0 +1,88 @@
+/**
+ * `swarmdo ownership` — per-file knowledge map + BUS FACTOR mined from git history.
+ *
+ *   swarmdo ownership                      # knowledge map, most fragile files first
+ *   swarmdo ownership src --since 90d       # scope to a path + window
+ *   swarmdo ownership --top 10 --format json
+ *   swarmdo ownership --csv > ownership.csv
+ *
+ * "Who owns each file, and what breaks if they leave?" — the code-maat
+ * main-dev / bus-factor analysis. Files where one author owns nearly all the
+ * churn (bus factor 1) are key-person risks. Pairs with `hotspots` (change-risk)
+ * and `coupling` (co-change). Engine (../ownership/ownership.ts) is pure +
+ * tested; this captures the git log (the same `--numstat` dump those use).
+ */
+import { execFileSync } from 'node:child_process';
+import { output } from '../output.js';
+import { parseGitLog } from '../hotspots/hotspots.js';
+import { computeOwnership, repoBusFactor, formatOwnership, ownershipToCsv } from '../ownership/ownership.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 pathArg = ctx.args[0];
+    const since = typeof ctx.flags.since === 'string' ? ctx.flags.since : '1 year ago';
+    const top = numFlag(ctx.flags.top, 40);
+    const minChurn = numFlag(ctx.flags['min-churn'], 1);
+    const asJson = ctx.flags.format === 'json';
+    const asCsv = ctx.flags.csv === true;
+    // Same SOH-delimited numstat capture `hotspots` uses. `%aN` folds author
+    // name/email variants through `.mailmap` so one person is one owner. A
+    // positional pathspec scopes BOTH the file rows and the truck factor to that
+    // subtree (unlike `coupling`, per-file ownership survives a pathspec fine).
+    const args = ['log', '--no-merges', '--numstat', `--since=${normalizeSince(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 commits = parseGitLog(raw);
+    const files = computeOwnership(commits, { minChurn, top: top > 0 ? top : undefined });
+    const repo = repoBusFactor(commits);
+    if (asCsv) {
+        process.stdout.write(ownershipToCsv(files) + '\n');
+    }
+    else if (asJson) {
+        process.stdout.write(JSON.stringify({ generated: new Date().toISOString(), since, minChurn, repoBusFactor: repo, count: files.length, ownership: files }, null, 2) + '\n');
+    }
+    else if (files.length === 0) {
+        output.writeln(output.dim('no ownership data found — no matching git history in the window'));
+    }
+    else {
+        output.writeln(output.bold(`File ownership & bus factor (since ${since})`));
+        if (repo.factor > 0) {
+            const who = repo.authors.length <= 3 ? repo.authors.join(', ') : `${repo.authors.slice(0, 3).join(', ')} +${repo.authors.length - 3}`;
+            const flag = repo.factor === 1 ? '  ⚠ single point of knowledge' : '';
+            output.writeln(output.dim(`Repo truck factor: ${repo.factor} (${who} own >50% of churn)${flag}`));
+        }
+        output.writeln(formatOwnership(files));
+    }
+    return { success: true, exitCode: 0 };
+}
+export const ownershipCommand = {
+    name: 'ownership',
+    description: 'Map per-file authorship concentration + bus factor from git history — find the key-person risks (code-maat main-dev / knowledge map)',
+    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 40; 0 = all)', type: 'string' },
+        { name: 'min-churn', description: 'drop files with total churn below N (default 1)', type: 'string' },
+        { name: 'csv', description: 'export the knowledge map as CSV (for spreadsheets)', type: 'boolean' },
+    ],
+    examples: [
+        { command: 'swarmdo ownership src --since 6mo', description: 'Knowledge map under src/ in the last 6 months' },
+        { command: 'swarmdo ownership --top 10 --format json', description: 'Ten most fragile files as JSON, with repo truck factor' },
+        { command: 'swarmdo ownership --csv > ownership.csv', description: 'Export the ownership map to CSV' },
+    ],
+    action: run,
+};
+export default ownershipCommand;
+//# sourceMappingURL=ownership.js.map

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

@@ -78,13 +78,13 @@ function walk(o) {
             if (e.isDirectory()) {
                 if (SKIP_DIRS.has(e.name))
                     continue;
-                if (o.gitignore?.(rel + '/'))
-                    continue;
+                if (o.gitignore?.(rel, true))
+                    continue; // isDir=true → dir-only patterns (build/) prune the dir + its contents
                 stack.push(full);
             }
             else if (e.isFile()) {
-                if (o.gitignore?.(rel))
-                    continue;
+                if (o.gitignore?.(rel, false))
+                    continue; // isDir=false → a dir-only pattern (build/) must NOT drop a file named `build`
                 if (o.exclude?.(rel))
                     continue;
                 if (o.include && !o.include(rel))

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

@@ -15,6 +15,7 @@
 import { spawnSync } from 'node:child_process';
 import { output } from '../output.js';
 import { redactText, scanText, formatFindingsSummary } from '../redact/redact.js';
+import { toSarif } from '../redact/sarif.js';
 import { writeStdout } from '../util/stdout.js';
 function readStdin() {
     return new Promise((resolve) => {
@@ -74,6 +75,14 @@ async function run(ctx) {
     // Scan mode: report findings, never rewrite; exit non-zero if any secret.
     if (scanMode) {
         const findings = scanText(input, opts);
+        if (ctx.flags.sarif === true) {
+            const source = typeof ctx.flags.source === 'string' ? ctx.flags.source : undefined;
+            process.stdout.write(toSarif(findings, { artifactUri: source }) + '\n');
+            // Same gate as text --scan: exit 1 on any secret (a CI author piping to
+            // upload-sarif adds `|| true` so the upload step still runs).
+            const code = findings.length > 0 ? 1 : wrappedCode;
+            return { success: code === 0, exitCode: code };
+        }
         if (asJson) {
             process.stdout.write(JSON.stringify({ count: findings.length, findings }, null, 2) + '\n');
         }
@@ -110,6 +119,8 @@ export const redactCommand = {
     options: [
         { name: 'scan', description: 'scan only: report findings and exit 1 if any secret is present (CI gate), never rewrite', type: 'boolean' },
         { name: 'json', description: 'emit findings as JSON', type: 'boolean' },
+        { name: 'sarif', description: 'scan only: emit findings as a SARIF 2.1.0 report (pipe to github/codeql-action/upload-sarif for code-scanning alerts)', type: 'boolean' },
+        { name: 'source', description: 'with --sarif: artifact URI/path the findings are anchored to (a stream has no file by default)', type: 'string' },
         { name: 'keep', description: 'keep this many leading chars of each secret (default 3; 0 = full mask)', type: 'string' },
         { name: 'token', description: 'replacement token after the kept prefix (default [REDACTED])', type: 'string' },
         { name: 'no-entropy', description: 'disable the high-entropy keyword=value fallback', type: 'boolean' },

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

@@ -14,7 +14,7 @@ import * as path from 'node:path';
 import * as os from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { output } from '../output.js';
-import { planRelease, renderStep } from '../release/release.js';
+import { planRelease, renderStep, resolveSiteIdentity, siteCommitArgs } from '../release/release.js';
 /** Escape every regex metacharacter (incl. backslash) so a value is a literal in `new RegExp`. */
 function escapeRegExp(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
@@ -125,13 +125,35 @@ async function executePlan(plan, root) {
                 }
                 const g = (args) => { execFileSync('git', args, { cwd: siteDir, stdio: 'inherit' }); };
                 g(['add', '-A']);
-                try {
-                    g(['commit', '-m', `release: sync site for v${plan.next}\n\nCo-Authored-By: Swarmdo <maintainers@swarmdo.com>`]);
-                }
-                catch {
+                // Only a genuinely empty index is the benign "in sync" case. Detect it
+                // explicitly — `git diff --cached --quiet` exits 0 iff nothing is staged
+                // — instead of treating EVERY commit failure (a missing git identity, a
+                // rejected hook) as a no-op, which silently skipped the whole deploy. (#82)
+                const nothingStaged = (() => {
+                    try {
+                        execFileSync('git', ['diff', '--cached', '--quiet'], { cwd: siteDir, stdio: ['ignore', 'pipe', 'pipe'] });
+                        return true;
+                    }
+                    catch {
+                        return false;
+                    }
+                })();
+                if (nothingStaged) {
                     output.writeln(output.dim('  site already in sync — nothing to commit'));
                     break;
                 }
+                // The throwaway clone inherits no git identity; inject the operator's
+                // (falling back to the Swarmdo bot) so the commit doesn't die on a
+                // machine whose git user is configured only per-repo, not globally. (#82)
+                const readCfg = (key) => {
+                    try {
+                        return execFileSync('git', ['-C', root, 'config', key], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+                    }
+                    catch {
+                        return '';
+                    }
+                };
+                g(siteCommitArgs(plan.next, resolveSiteIdentity(readCfg)));
                 g(['push', 'origin', 'main']);
                 // poll production (GitHub Pages deploys in ~1min)
                 let live = false;

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/commands-lint.d.ts

@@ -0,0 +1,31 @@
+/**
+ * commands-lint.ts — static validation of Claude Code custom slash commands
+ * (the `.claude/commands` tree) and skills (`.claude/skills/<name>/SKILL.md`).
+ *
+ * Slash commands / skills are the most-copied Claude Code power-user artifact,
+ * and CC swallows their footguns silently: malformed YAML frontmatter makes CC
+ * load the body with EMPTY metadata (so `/cmd` "works" typed but Claude can
+ * never auto-match it), and two body rules bite in ways manual review misses —
+ * an inline `` !`cmd` `` that isn't at a line start / after whitespace is left as
+ * literal text and NEVER runs, and one whose command no `allowed-tools` Bash
+ * rule covers prompts/blocks instead of running pre-approved. This catches those
+ * before CC does. Sibling of agents-lint; same `Finding` shape.
+ *
+ * Pure: parsed text in, findings out. Reuses the permission-rule matcher
+ * (parseRule/covers) so allowed-tools coverage matches Claude Code's own glob
+ * semantics. Only truly-bounded fields are enum-checked (NOT `model`, which
+ * accepts aliases and full IDs) to stay false-positive-safe.
+ */
+import type { Finding } from './lint.js';
+/** Reasoning-effort levels a command/skill `effort:` field may name. */
+export declare const EFFORT_LEVELS: string[];
+/** Lint ONE command/skill file's raw text. `kind` toggles the skill-only rule
+ * that frontmatter (with name + description) is REQUIRED. Pure. */
+export declare function lintCommandFile(file: string, raw: string, kind?: 'command' | 'skill'): Finding[];
+export interface CommandFile {
+    file: string;
+    raw: string;
+}
+/** Lint a set of command files and skill files. Pure. */
+export declare function lintCommandFiles(commands: CommandFile[], skills?: CommandFile[]): Finding[];
+//# sourceMappingURL=commands-lint.d.ts.map

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

@@ -0,0 +1,127 @@
+/**
+ * commands-lint.ts — static validation of Claude Code custom slash commands
+ * (the `.claude/commands` tree) and skills (`.claude/skills/<name>/SKILL.md`).
+ *
+ * Slash commands / skills are the most-copied Claude Code power-user artifact,
+ * and CC swallows their footguns silently: malformed YAML frontmatter makes CC
+ * load the body with EMPTY metadata (so `/cmd` "works" typed but Claude can
+ * never auto-match it), and two body rules bite in ways manual review misses —
+ * an inline `` !`cmd` `` that isn't at a line start / after whitespace is left as
+ * literal text and NEVER runs, and one whose command no `allowed-tools` Bash
+ * rule covers prompts/blocks instead of running pre-approved. This catches those
+ * before CC does. Sibling of agents-lint; same `Finding` shape.
+ *
+ * Pure: parsed text in, findings out. Reuses the permission-rule matcher
+ * (parseRule/covers) so allowed-tools coverage matches Claude Code's own glob
+ * semantics. Only truly-bounded fields are enum-checked (NOT `model`, which
+ * accepts aliases and full IDs) to stay false-positive-safe.
+ */
+import { parse as parseYaml } from 'yaml';
+import { parseRule, covers } from '../permissions/audit.js';
+const f = (file, severity, rule, message) => ({ file, severity, rule, message });
+/** Reasoning-effort levels a command/skill `effort:` field may name. */
+export const EFFORT_LEVELS = ['low', 'medium', 'high', 'xhigh', 'max'];
+const FRONTMATTER_RE = /^---[ \t]*\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n([\s\S]*))?$/;
+function parseFile(raw) {
+    const text = raw.replace(/^\uFEFF/, '');
+    const m = text.match(FRONTMATTER_RE);
+    if (!m) {
+        // An opening `---` with no closing fence is malformed; anything else is a
+        // plain-markdown command (no frontmatter — perfectly valid).
+        if (/^---[ \t]*\r?\n/.test(text))
+            return { meta: null, body: text, malformed: 'has an opening `---` but no closing `---` fence' };
+        return { meta: null, body: text };
+    }
+    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 };
+}
+/**
+ * Inline bash-injection placeholders `` !`cmd` `` in the body. Claude Code only
+ * RUNS one whose `!` is at a line start or immediately after whitespace; if `!`
+ * follows another character (e.g. `` KEY=!`cmd` ``) it is left as literal text.
+ */
+function bashInjections(body) {
+    const out = [];
+    const re = /!`([^`\n]+)`/g;
+    let m;
+    while ((m = re.exec(body)) !== null) {
+        const at = m.index;
+        const active = at === 0 || /\s/.test(body[at - 1]);
+        out.push({ cmd: m[1].trim(), active });
+    }
+    return out;
+}
+/** Parse the `allowed-tools` frontmatter (string list or YAML array) into rules;
+ * null = the key is absent (no pre-approval declared, so coverage isn't checked). */
+function allowedToolRules(meta) {
+    const at = meta['allowed-tools'] ?? meta['allowedTools'];
+    if (at === undefined)
+        return null;
+    const parts = Array.isArray(at) ? at.map(String) : typeof at === 'string' ? at.split(',') : [];
+    const rules = [];
+    for (const p of parts) {
+        const r = parseRule(p.trim());
+        if (r.tool !== undefined)
+            rules.push(r);
+    }
+    return rules;
+}
+/** Lint ONE command/skill file's raw text. `kind` toggles the skill-only rule
+ * that frontmatter (with name + description) is REQUIRED. Pure. */
+export function lintCommandFile(file, raw, kind = 'command') {
+    const p = parseFile(raw);
+    const out = [];
+    if (p.malformed) {
+        out.push(f(file, 'error', 'command-malformed-frontmatter', p.malformed));
+    }
+    else if (kind === 'skill' && !p.meta) {
+        out.push(f(file, 'error', 'skill-missing-frontmatter', 'a SKILL.md must start with a `---` … `---` frontmatter block declaring `name` and `description`'));
+    }
+    const meta = p.meta;
+    if (meta) {
+        if (kind === 'skill' && (typeof meta.name !== 'string' || meta.name.trim() === '')) {
+            out.push(f(file, 'error', 'skill-missing-name', 'frontmatter is missing a non-empty `name`'));
+        }
+        if (typeof meta.description !== 'string' || meta.description.trim() === '') {
+            const how = kind === 'skill' ? 'decide when to invoke the skill' : 'list the command and model-invoke it';
+            out.push(f(file, kind === 'skill' ? 'error' : 'warn', 'command-missing-description', `frontmatter has no non-empty \`description\` (Claude Code uses it to ${how})`));
+        }
+        if (meta.effort !== undefined && !EFFORT_LEVELS.includes(String(meta.effort))) {
+            out.push(f(file, 'error', 'command-bad-effort', `effort "${String(meta.effort)}" is not one of: ${EFFORT_LEVELS.join(', ')}`));
+        }
+    }
+    // Body cross-checks (both kinds). Coverage is only checked when allowed-tools
+    // is declared — otherwise the author never opted into pre-approval.
+    const rules = meta ? allowedToolRules(meta) : null;
+    for (const inj of bashInjections(p.body)) {
+        const tok = '!`' + inj.cmd + '`';
+        if (!inj.active) {
+            out.push(f(file, 'warn', 'command-inert-bash-injection', `inline bash ${tok} follows a non-whitespace character — Claude Code leaves it as literal text and never runs it (put \`!\` at a line start or after whitespace)`));
+            continue;
+        }
+        if (rules && rules.length > 0 && !rules.some((r) => covers(r, { tool: 'Bash', specifier: inj.cmd }))) {
+            out.push(f(file, 'warn', 'command-uncovered-bash-injection', `inline bash ${tok} is not covered by any \`allowed-tools\` Bash rule — it will prompt/block instead of running pre-approved`));
+        }
+    }
+    return out;
+}
+/** Lint a set of command files and skill files. Pure. */
+export function lintCommandFiles(commands, skills = []) {
+    const out = [];
+    for (const c of commands)
+        out.push(...lintCommandFile(c.file, c.raw, 'command'));
+    for (const s of skills)
+        out.push(...lintCommandFile(s.file, s.raw, 'skill'));
+    return out;
+}
+//# sourceMappingURL=commands-lint.js.map

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

@@ -17,6 +17,8 @@ export interface Finding {
 }
 export declare const TOPOLOGIES: string[];
 export declare const MEMORY_BACKENDS: string[];
+import { type AgentFile } from './agents-lint.js';
+import { type CommandFile } from './commands-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 +51,12 @@ 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[];
+    /** custom slash commands under the `.claude/commands` tree (raw text per file) */
+    commandFiles?: CommandFile[];
+    /** skill definitions at `.claude/skills/<name>/SKILL.md` (raw text per file) */
+    skillFiles?: CommandFile[];
 }
 export interface LintReport {
     findings: Finding[];

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

@@ -12,6 +12,8 @@ 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';
+import { lintCommandFiles } from './commands-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 +196,11 @@ 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));
+    if (input.commandFiles?.length || input.skillFiles?.length) {
+        findings.push(...lintCommandFiles(input.commandFiles ?? [], input.skillFiles ?? []));
+    }
     return {
         findings,
         errors: findings.filter((x) => x.severity === 'error').length,