Skip to content

armgit / ruflo

Public Imported from GitHub
0

🌊 The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated

feat(mods): doctor names each broken state with a one-line repair, --strict, atomic install with rollback

re1c9d75590ca
diff --git a/v3/@claude-flow/cli/__tests__/mods/mods-hardening.test.ts b/v3/@claude-flow/cli/__tests__/mods/mods-hardening.test.ts
new file mode 100644
index 0000000000..b9416a9134
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/mods/mods-hardening.test.ts
@@ -0,0 +1,149 @@
+/**
+ * ADR-404 hardening — `ruflo mods doctor` names each broken state with a one-line repair that actually
+ * repairs it, `--strict` makes a warning fail, and `ruflo mods install` is one operation: when the
+ * record cannot be written the settings are put back (nothing half-installed).
+ */
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { ENABLE_ENV, INSTALL_RECORD, installMod, MOD_PLUGIN_ID, MOD_PLUGIN_IDS } from '../../src/mods/install.js';
+import { probeMods, type Finding } from '../../src/mods/probe.js';
+import { hasFailureOrStrictWarning } from '../../src/commands/mods.js';
+
+let root: string;
+let home: string;
+beforeEach(() => {
+ root = mkdtempSync(join(tmpdir(), 'ruflo-mods-hard-'));
+ home = mkdtempSync(join(tmpdir(), 'ruflo-mods-hard-home-'));
+});
+afterEach(() => {
+ rmSync(root, { recursive: true, force: true });
+ rmSync(home, { recursive: true, force: true });
+});
+
+const settingsPath = (name = 'settings.local.json') => join(root, '.claude', name);
+const writeSettings = (value: unknown, name = 'settings.local.json') => {
+ mkdirSync(join(root, '.claude'), { recursive: true });
+ writeFileSync(settingsPath(name), JSON.stringify(value));
+};
+const probe = (extra: Record<string, unknown> = {}): Finding[] =>
+ probeMods({ projectRoot: root, home, configDir: join(home, '.claude'), env: {}, managedPath: join(home, 'none.json'), installs: [], ...extra });
+const named = (findings: Finding[], name: string) => findings.find((f) => f.name === name);
+
+describe('doctor: a plugin switched off is not repaired by `mods install`', () => {
+ it('names the plugin as disabled and repairs it with `claude plugin enable`, not `ruflo mods install`', () => {
+ writeSettings({ enabledPlugins: { [MOD_PLUGIN_ID]: false } });
+ const f = named(probe(), 'ruflo-mods plugin')!;
+ expect(f.status).toBe('warn');
+ expect(f.message).toMatch(/disabled/i);
+ expect(f.fix).toContain('claude plugin enable ruflo-mods@ruflo');
+ expect(f.fix).not.toContain('ruflo mods install');
+ });
+
+ it('a plugin that is installed for this project but enabled nowhere says so', () => {
+ const cfg = join(home, '.claude');
+ const cache = join(cfg, 'plugins', 'cache', 'ruflo', 'ruflo-mods', '1.0.0');
+ mkdirSync(cache, { recursive: true });
+ mkdirSync(join(cfg, 'plugins'), { recursive: true });
+ writeFileSync(join(cfg, 'plugins', 'installed_plugins.json'), JSON.stringify({ version: 2, plugins: { [MOD_PLUGIN_ID]: [{ scope: 'user', installPath: cache }] } }));
+ const f = named(probe(), 'ruflo-mods plugin')!;
+ expect(f.status).toBe('warn');
+ expect(f.message).toMatch(/installed .*not enabled/i);
+ expect(f.fix).toMatch(/claude plugin enable ruflo-mods@ruflo|ruflo mods install/);
+ });
+});
+
+describe('doctor: a partial install', () => {
+ it('flags mods enabled without the swarm and console plugins, with `ruflo mods install` as the repair', () => {
+ writeSettings({ enabledPlugins: { [MOD_PLUGIN_ID]: true }, env: { [ENABLE_ENV]: '1' }, extraKnownMarketplaces: { ruflo: { source: { source: 'github', repo: 'ruvnet/ruflo' } } } });
+ const f = named(probe(), 'partial install')!;
+ expect(f).toBeDefined();
+ expect(f.status).toBe('warn');
+ expect(f.message).toContain('ruflo-swarm@ruflo');
+ expect(f.message).toContain('ruflo-console@ruflo');
+ expect(f.fix).toBe('ruflo mods install');
+ });
+
+ it('flags a plugin enabled with no marketplace declared anywhere', () => {
+ writeSettings({ enabledPlugins: Object.fromEntries(MOD_PLUGIN_IDS.map((id) => [id, true])), env: { [ENABLE_ENV]: '1' } });
+ const f = named(probe(), 'partial install')!;
+ expect(f.status).toBe('warn');
+ expect(f.message).toMatch(/marketplace/);
+ });
+
+ it('flags keys the install record says ruflo added but the settings file no longer has', () => {
+ installMod(root, 'local');
+ const file = settingsPath();
+ const s = JSON.parse(readFileSync(file, 'utf8'));
+ delete s.enabledPlugins['ruflo-console@ruflo'];
+ writeFileSync(file, JSON.stringify(s));
+ const f = named(probe(), 'partial install')!;
+ expect(f.status).toBe('warn');
+ expect(f.message).toContain('ruflo-console@ruflo');
+ });
+
+ it('is quiet after a complete install and when nothing is installed at all', () => {
+ expect(named(probe(), 'partial install')).toBeUndefined();
+ installMod(root, 'local');
+ expect(named(probe(), 'partial install')?.status ?? 'pass').toBe('pass');
+ });
+});
+
+describe('doctor: every non-passing finding carries a one-line repair', () => {
+ it('a fresh project with the mod enabled but nothing cloned, nothing cached and function hooks unproven', () => {
+ installMod(root, 'local');
+ const bad = probe().filter((f) => f.status !== 'pass');
+ expect(bad.length).toBeGreaterThan(0);
+ for (const f of bad) {
+ // The only findings allowed without a command are engine-side facts a person cannot change.
+ if (f.name === 'function hooks' && /serves function hooks OFF/.test(f.message)) continue;
+ expect(f.fix, `${f.name}: ${f.message}`).toBeTruthy();
+ expect(f.fix!.includes('\n'), `${f.name} fix is one line`).toBe(false);
+ }
+ });
+});
+
+describe('doctor --strict', () => {
+ const warn: Finding = { name: 'x', status: 'warn', message: 'm', fix: 'f' };
+ const pass: Finding = { name: 'y', status: 'pass', message: 'm' };
+ const fail: Finding = { name: 'z', status: 'fail', message: 'm', fix: 'f' };
+ it('fails on a warning only when strict; always fails on a failure', () => {
+ expect(hasFailureOrStrictWarning([pass, warn], false)).toBe(false);
+ expect(hasFailureOrStrictWarning([pass, warn], true)).toBe(true);
+ expect(hasFailureOrStrictWarning([pass, fail], false)).toBe(true);
+ expect(hasFailureOrStrictWarning([pass], true)).toBe(false);
+ });
+});
+
+describe('install is one operation', () => {
+ it('puts the settings back when the install record cannot be written', () => {
+ writeSettings({ hooks: { Stop: [] }, env: { KEEP: 'x' } });
+ const before = readFileSync(settingsPath(), 'utf8');
+ // The record's folder cannot be created: .claude-flow is a file.
+ writeFileSync(join(root, '.claude-flow'), 'not a folder');
+ expect(() => installMod(root, 'local')).toThrow();
+ expect(readFileSync(settingsPath(), 'utf8')).toBe(before);
+ });
+
+ it('removes a settings file it created when the record cannot be written', () => {
+ writeFileSync(join(root, '.claude-flow'), 'not a folder');
+ expect(existsSync(settingsPath())).toBe(false);
+ expect(() => installMod(root, 'local')).toThrow();
+ expect(existsSync(settingsPath())).toBe(false);
+ });
+
+ it('a second run changes nothing and writes no second backup', () => {
+ installMod(root, 'local');
+ const first = readFileSync(settingsPath(), 'utf8');
+ const record = readFileSync(join(root, INSTALL_RECORD), 'utf8');
+ const again = installMod(root, 'local');
+ expect(again.added).toEqual({ plugins: [], marketplace: false, env: false });
+ expect(again.backup).toBeUndefined();
+ expect(readFileSync(settingsPath(), 'utf8')).toBe(first);
+ expect(readFileSync(join(root, INSTALL_RECORD), 'utf8')).toBe(record);
+ });
+});
+
+void chmodSync;
diff --git a/v3/@claude-flow/cli/src/commands/mods.ts b/v3/@claude-flow/cli/src/commands/mods.ts
index 05d6e6423c..077c31e4f7 100644
--- a/v3/@claude-flow/cli/src/commands/mods.ts
+++ b/v3/@claude-flow/cli/src/commands/mods.ts
@@ -108,17 +108,31 @@ const uninstallSub: Command = {
},
};
+/** The doctor's exit gate: a failure always fails; with --strict a warning does too. */
+export function hasFailureOrStrictWarning(findings: readonly Finding[], strict: boolean): boolean {
+ return findings.some((f) => f.status === 'fail' || (strict && f.status === 'warn'));
+}
+
function findingsCommand(name: 'status' | 'doctor', description: string): Command {
return {
name,
description,
- options: [rootOption, { name: 'json', description: 'Output as JSON', type: 'boolean', default: false }],
+ options: [
+ rootOption,
+ { name: 'json', description: 'Output as JSON', type: 'boolean', default: false },
+ ...(name === 'doctor' ? [{ name: 'strict', description: 'Exit 1 on a warning too (a mod that is not fully loaded is a failure for a CI gate)', type: 'boolean' as const, default: false }] : []),
+ ],
action: async (ctx: CommandContext): Promise<CommandResult> => {
const findings = probeMods({ projectRoot: projectRoot(ctx) });
if (ctx.flags.json) output.printJson(findings);
else printFindings(findings);
- const failed = findings.some((f) => f.status === 'fail');
- // status reports (exit 0); doctor gates on a failure (warnings are expected while early access is off).
+ const strict = name === 'doctor' && ctx.flags.strict === true;
+ const failed = hasFailureOrStrictWarning(findings, strict);
+ if (failed && !ctx.flags.json) {
+ const first = findings.find((f) => f.status === 'fail') ?? findings.find((f) => f.status === 'warn');
+ output.writeln(output.error(`doctor: ${findings.filter((f) => f.status === 'fail').length} failure(s), ${findings.filter((f) => f.status === 'warn').length} warning(s)${first?.fix ? `; start with: ${first.fix}` : ''}`));
+ }
+ // status reports (exit 0); doctor gates on a failure, and with --strict on a warning.
return name === 'doctor' && failed ? { success: false, exitCode: 1, data: findings } : { success: true, data: findings };
},
};
@@ -156,7 +170,7 @@ export const modsCommand: Command = {
installSub,
uninstallSub,
statusSub,
- findingsCommand('doctor', 'Check the mod path; exits 1 only on a failure'),
+ findingsCommand('doctor', 'Check the mod path; exits 1 on a failure (--strict: on a warning too)'),
syncPolicySub,
],
examples: [
@@ -164,7 +178,8 @@ export const modsCommand: Command = {
{ command: 'ruflo mods install --scope project', description: 'Same, in the committed settings.json (what ruflo init does)' },
{ command: 'ruflo mods install --no-plugin-install', description: 'Only write settings; run no claude command' },
{ command: 'ruflo mods install --source local', description: 'Dogfood: load the mods live from this ruflo checkout (directory marketplace)' },
- { command: 'ruflo mods doctor', description: 'Marketplace fresh? Plugins loadable? Function hooks on? Refused by policy?' },
+ { command: 'ruflo mods doctor', description: 'Marketplace fresh? Plugins loadable? Function hooks on? Refused by policy? Each problem prints a one-line fix' },
+ { command: 'ruflo mods doctor --strict', description: 'Same, and exit 1 when anything is not fully working (for CI)' },
{ command: 'ruflo mods uninstall', description: 'Remove only what install added' },
],
action: statusSub.action,
diff --git a/v3/@claude-flow/cli/src/mods/claude-installs.ts b/v3/@claude-flow/cli/src/mods/claude-installs.ts
index 3523d805e9..0777913454 100644
--- a/v3/@claude-flow/cli/src/mods/claude-installs.ts
+++ b/v3/@claude-flow/cli/src/mods/claude-installs.ts
@@ -81,13 +81,17 @@ export function judgeInstalls(installs: readonly ClaudeInstall[], enableEnvSet:
? `; also installed: ${others.map((i) => `${i.path} (${i.version ?? 'unknown'})`).join(', ')}. The first on PATH runs; a stale one can shadow a current one.`
: '';
const runs = `${first!.path} (${first!.version ?? 'version unknown'})`;
- if (!first!.version) return { status: 'warn', message: `claude resolves to ${runs}${mixed}` };
+ if (!first!.version) return { status: 'warn', message: `claude resolves to ${runs}${mixed}`, fix: `run \`${first!.path} --version\` and reinstall Claude Code if it prints nothing` };
if (!versionLess(first!.version, MODS_DEFAULT_ON)) {
- return { status: others.length ? 'warn' : 'pass', message: `claude resolves to ${runs}: mods on by default${mixed}` };
+ return others.length
+ ? { status: 'warn', message: `claude resolves to ${runs}: mods on by default${mixed}`, fix: `put the claude you want first on PATH, or remove: ${others.map((i) => i.path).join(' ')}` }
+ : { status: 'pass', message: `claude resolves to ${runs}: mods on by default` };
}
if (!versionLess(first!.version, MODS_FIRST)) {
return enableEnvSet
- ? { status: others.length ? 'warn' : 'pass', message: `claude resolves to ${runs}: mods load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (set)${mixed}` }
+ ? (others.length
+ ? { status: 'warn' as const, message: `claude resolves to ${runs}: mods load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (set)${mixed}`, fix: `put the claude you want first on PATH, or remove: ${others.map((i) => i.path).join(' ')}` }
+ : { status: 'pass' as const, message: `claude resolves to ${runs}: mods load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (set)` })
: { status: 'warn', message: `claude resolves to ${runs}: below ${MODS_DEFAULT_ON}, mods need CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (not set)${mixed}`, fix: `upgrade to >= ${MODS_DEFAULT_ON}, or export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1` };
}
return { status: 'warn', message: `claude resolves to ${runs}: predates mods (< ${MODS_FIRST}); classic hooks handle every event${mixed}`, fix: `upgrade to >= ${MODS_DEFAULT_ON} and remove the stale install from PATH` };
diff --git a/v3/@claude-flow/cli/src/mods/install.ts b/v3/@claude-flow/cli/src/mods/install.ts
index a22b8ecf9a..674ac75dcf 100644
--- a/v3/@claude-flow/cli/src/mods/install.ts
+++ b/v3/@claude-flow/cli/src/mods/install.ts
@@ -163,18 +163,35 @@ export function installMod(
backup = `${settingsFile}.bak-ruflo-mods-${Date.now()}`;
copyFileSync(settingsFile, backup);
}
- writeJson(settingsFile, next);
- // What ruflo added once is still ruflo's to remove: merge into the record.
- const record = readRecord(projectRoot) ?? { version: 2, installedAt: '', files: {} };
- const before = record.files[settingsFile] ?? { plugins: [], marketplace: false, env: false };
- record.files[settingsFile] = {
- plugins: [...new Set([...before.plugins, ...added.plugins])],
- marketplace: before.marketplace || added.marketplace,
- env: before.env || added.env,
- claudeInstalled: before.claudeInstalled ?? [],
- };
- record.installedAt = new Date().toISOString();
- writeJson(join(resolve(projectRoot), INSTALL_RECORD), record);
+ // One operation: the settings and the record that lets uninstall take them back are written together.
+ // If the record cannot be written, the settings go back as they were (or the file ruflo created goes
+ // away), so nothing is left half-installed with no record to remove it by.
+ try {
+ writeJson(settingsFile, next);
+ // What ruflo added once is still ruflo's to remove: merge into the record.
+ const record = readRecord(projectRoot) ?? { version: 2, installedAt: '', files: {} };
+ const before = record.files[settingsFile] ?? { plugins: [], marketplace: false, env: false };
+ record.files[settingsFile] = {
+ plugins: [...new Set([...before.plugins, ...added.plugins])],
+ marketplace: before.marketplace || added.marketplace,
+ env: before.env || added.env,
+ claudeInstalled: before.claudeInstalled ?? [],
+ };
+ record.installedAt = new Date().toISOString();
+ writeJson(join(resolve(projectRoot), INSTALL_RECORD), record);
+ } catch (error) {
+ try {
+ if (backup) {
+ copyFileSync(backup, settingsFile);
+ unlinkSync(backup);
+ } else if (existsSync(settingsFile)) {
+ unlinkSync(settingsFile);
+ }
+ } catch {
+ // the restore itself failed: the original error below is the one to report
+ }
+ throw error;
+ }
return { settingsFile, backup, added, dryRun, next };
}
diff --git a/v3/@claude-flow/cli/src/mods/plugin-resolve.ts b/v3/@claude-flow/cli/src/mods/plugin-resolve.ts
index a0ac9d35f6..e1f8e585c7 100644
--- a/v3/@claude-flow/cli/src/mods/plugin-resolve.ts
+++ b/v3/@claude-flow/cli/src/mods/plugin-resolve.ts
@@ -201,7 +201,9 @@ export function resolveFindings(
} else if (!market.location) {
findings.push(installed.installed
? { name, status: 'pass', message: `installed (${installed.scope} scope, ${installed.installPath})` }
- : { name, status: 'warn', message: plugin.required ? 'loads once Claude Code has cloned the marketplace' : 'pending: not released in the ruflo marketplace yet' });
+ : plugin.required
+ ? { name, status: 'warn', message: 'loads once Claude Code has cloned the marketplace (a headless `claude -p` run on a fresh config does not clone it, so the mod is absent there)', fix }
+ : { name, status: 'warn', message: 'pending: not released in the ruflo marketplace yet' });
} else if (!plugin.required) {
findings.push({ name, status: 'warn', message: `pending: not in the ruflo marketplace yet (${market.location})${also}` });
} else if (installed.installed) {
diff --git a/v3/@claude-flow/cli/src/mods/probe.ts b/v3/@claude-flow/cli/src/mods/probe.ts
index ebea21e479..7132c09fca 100644
--- a/v3/@claude-flow/cli/src/mods/probe.ts
+++ b/v3/@claude-flow/cli/src/mods/probe.ts
@@ -10,8 +10,8 @@ import { homedir, platform } from 'node:os';
import { join, resolve } from 'node:path';
import { findClaudeInstalls, judgeInstalls, type ClaudeInstall } from './claude-installs.js';
-import { ENABLE_ENV, MOD_PLUGIN_ID, MOD_PLUGIN_IDS, readRecord, readSettingsFile, settingsFileFor } from './install.js';
-import { claudeConfigDir, resolveFindings, type ReadFs } from './plugin-resolve.js';
+import { ENABLE_ENV, MARKETPLACE_NAME, MOD_PLUGIN_ID, MOD_PLUGIN_IDS, readRecord, readSettingsFile, settingsFileFor } from './install.js';
+import { claudeConfigDir, installedState, resolveFindings, type ReadFs } from './plugin-resolve.js';
import { PROJECTION_RELATIVE } from './policy-projection.js';
export const HANDSHAKE_MARKER = 'RUFLO_MODS_OWNS';
@@ -79,6 +79,59 @@ export function legacyCliHooks(files: readonly string[]): Array<keyof typeof LEG
});
}
+
+/** Settings files (in the order given) where `enabledPlugins[id]` is exactly `value`. */
+function enabledValues(files: readonly string[], id: string): Map<string, unknown> {
+ const out = new Map<string, unknown>();
+ for (const f of files) {
+ try {
+ const v = get(readSettingsFile(f), 'enabledPlugins', id);
+ if (v !== undefined) out.set(f, v);
+ } catch {
+ // an unparseable file is reported elsewhere; never overwritten
+ }
+ }
+ return out;
+}
+
+function partialInstallFindings(root: string, files: readonly string[], _inputs: ProbeInputs): Finding[] {
+ const enabled = new Set(MOD_PLUGIN_IDS.filter((id) => [...enabledValues(files, id).values()].includes(true)));
+ const out: Finding[] = [];
+ const parts: string[] = [];
+
+ if (enabled.size > 0 && enabled.size < MOD_PLUGIN_IDS.length) {
+ const missing = MOD_PLUGIN_IDS.filter((id) => !enabled.has(id) && ![...enabledValues(files, id).values()].includes(false));
+ if (missing.length) parts.push(`enabled ${[...enabled].join(', ')} but not ${missing.join(', ')}`);
+ }
+ if (enabled.size > 0) {
+ const declared = files.some((f) => {
+ try {
+ return get(readSettingsFile(f), 'extraKnownMarketplaces', MARKETPLACE_NAME) !== undefined;
+ } catch {
+ return false;
+ }
+ });
+ if (!declared) parts.push(`no \`${MARKETPLACE_NAME}\` marketplace is declared in settings for Claude Code to load them from`);
+ }
+ const record = readRecord(root);
+ if (record) {
+ const lost: string[] = [];
+ for (const [file, added] of Object.entries(record.files)) {
+ try {
+ const now = readSettingsFile(file);
+ for (const id of added.plugins) if (get(now, 'enabledPlugins', id) !== true && get(now, 'enabledPlugins', id) !== false) lost.push(id);
+ if (added.marketplace && get(now, 'extraKnownMarketplaces', MARKETPLACE_NAME) === undefined) lost.push(`${MARKETPLACE_NAME} marketplace`);
+ } catch {
+ // unreadable settings: nothing to compare
+ }
+ }
+ if (lost.length) parts.push(`the install record says ruflo added ${[...new Set(lost)].join(', ')}, which the settings no longer have`);
+ }
+
+ if (parts.length) out.push({ name: 'partial install', status: 'warn', message: parts.join('; '), fix: 'ruflo mods install' });
+ return out;
+}
+
export function probeMods(inputs: ProbeInputs): Finding[] {
const root = resolve(inputs.projectRoot);
const home = inputs.home ?? homedir();
@@ -95,9 +148,38 @@ export function probeMods(inputs: ProbeInputs): Finding[] {
return false;
}
});
+ // A plugin a person set to false is their decision: `ruflo mods install` never flips it, so it is not the repair.
+ const disabledIn = enabledIn ? undefined : files.find((f) => {
+ try {
+ return get(readSettingsFile(f), 'enabledPlugins', MOD_PLUGIN_ID) === false;
+ } catch {
+ return false;
+ }
+ });
+ const cachedInstall = enabledIn || disabledIn ? { installed: false as const } : installedState(root, configDir, MOD_PLUGIN_ID, inputs.fs);
+ const scopeOf = (f: string) => (f === files[0] ? 'local' : f === files[1] ? 'project' : 'user');
findings.push(enabledIn
? { name: 'ruflo-mods plugin', status: 'pass', message: `enabled in settings: ${enabledIn} (whether Claude Code can load it: see below)` }
- : { name: 'ruflo-mods plugin', status: 'warn', message: 'not enabled; classic hooks handle every event', fix: 'ruflo mods install' });
+ : disabledIn
+ ? {
+ name: 'ruflo-mods plugin',
+ status: 'warn',
+ message: `disabled in ${disabledIn} (enabledPlugins is false): the mod does not load and classic hooks handle every event; \`ruflo mods install\` leaves a plugin you switched off alone`,
+ fix: `claude plugin enable ${MOD_PLUGIN_ID} --scope ${scopeOf(disabledIn)}`,
+ }
+ : cachedInstall.installed
+ ? {
+ name: 'ruflo-mods plugin',
+ status: 'warn',
+ message: `installed (${cachedInstall.scope} scope) but not enabled in this project's settings: the mod does not load`,
+ fix: `claude plugin enable ${MOD_PLUGIN_ID} --scope ${cachedInstall.scope === 'user' ? 'user' : 'local'}`,
+ }
+ : { name: 'ruflo-mods plugin', status: 'warn', message: 'not enabled; classic hooks handle every event', fix: 'ruflo mods install' });
+
+ // 1b. A half-finished install: some of the mod plugins enabled and not the rest, a plugin enabled with no
+ // marketplace declared for Claude Code to load it from, or keys the install record says ruflo added that
+ // the settings file no longer has. `ruflo mods install` is idempotent and adds exactly what is missing.
+ findings.push(...partialInstallFindings(root, files, inputs));
// 1a. Enabled is a request; Claude Code silently skips a plugin its
// marketplace clone does not carry (a clone older than the plugin).
@@ -193,7 +275,7 @@ export function probeMods(inputs: ProbeInputs): Finding[] {
const owned = get(beat, 'owned');
findings.push(typeof startedAt === 'string'
? { name: 'last mod start', status: 'pass', message: `${startedAt}, owning ${Array.isArray(owned) && owned.length ? owned.join(', ') : 'nothing'}` }
- : { name: 'last mod start', status: enabledIn ? 'warn' : 'pass', message: 'the mod has not started in this project' + (enabledIn ? ' (restart Claude Code; check function hooks above)' : '') });
+ : { name: 'last mod start', status: enabledIn ? 'warn' : 'pass', message: 'the mod has not started in this project' + (enabledIn ? ' (restart Claude Code; check function hooks above)' : ''), ...(enabledIn ? { fix: 'restart Claude Code in this project, then run /ruflo mods' } : {}) });
if (readRecord(root)) findings.push({ name: 'install record', status: 'pass', message: join(root, '.claude-flow', 'mods', 'install.json') });
return findings;