@claude-flow/cli 3.25.5 → 3.26.0

package/.claude/proven-config.json

@@ -0,0 +1,42 @@
+{
+  "adoptedAt": 1783692950735,
+  "championId": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+  "manifest": {
+    "schema": "ruflo.proven-config/v1",
+    "policy": {
+      "ref": "sha256:6141a8ea990c5063b77e090ae8f37f9c539d8aa8f58dcceb30f3a82f97e57319",
+      "value": {
+        "alpha": 0.3,
+        "subjectWeight": 1,
+        "mmrLambda": 0.5,
+        "bodyWeight": 1.5,
+        "typePenaltyFactor": 0.5
+      }
+    },
+    "layer": "framework/node-cli",
+    "compatibility": {
+      "ruflo": ">=3.24.0"
+    },
+    "benchmark": {
+      "corpus": "ADR-081-labelled-v1",
+      "corpusHash": "sha256:2f700b5c363e20a3bd88ce2bc9b87bbbbaa61732c6177894c6ec37890f888982"
+    },
+    "receipt": {
+      "heldOutDelta": 0.07381404928570845,
+      "redblue": "PASS",
+      "drift": 0,
+      "canary": {
+        "rollbackRate": 0,
+        "latencyP95": 244.612458000076,
+        "costPerTask": 0
+      },
+      "receiptCoverage": 1
+    },
+    "platform": [
+      "linux",
+      "macOS",
+      "windows"
+    ]
+  },
+  "previous": ""
+}

package/catalog-manifest.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "generation": 1,
+  "generatedAt": "2026-07-13T16:09:11.080Z",
+  "gitSha": "2d42012e",
+  "catalog": {
+    "agents": 164,
+    "tools": 387,
+    "skills": 34
+  },
+  "benchmark": null
+}

package/dist/src/commands/advisor.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `ruflo advisor` — Fable co-pilot advisor tip in the statusline insight
+ * ticker (ADR-316).
+ *
+ * Client-side only — unlike `proxy.ts`'s sponsored-downtime/power-saver/
+ * training-share domains, this feature has NO proxy-config.toml mirror,
+ * because it never talks to the meta-proxy Rust binary. It calls
+ * `claude -p` directly via services/fable-harness.ts (ADR-172's existing
+ * cost-disciplined harness) and caches the result for the insight ticker
+ * (funnel/insights.ts) to read synchronously.
+ */
+import type { Command } from '../types.js';
+export declare const advisorCommand: Command;
+export default advisorCommand;
+//# sourceMappingURL=advisor.d.ts.map

package/dist/src/commands/advisor.js

@@ -0,0 +1,94 @@
+/**
+ * `ruflo advisor` — Fable co-pilot advisor tip in the statusline insight
+ * ticker (ADR-316).
+ *
+ * Client-side only — unlike `proxy.ts`'s sponsored-downtime/power-saver/
+ * training-share domains, this feature has NO proxy-config.toml mirror,
+ * because it never talks to the meta-proxy Rust binary. It calls
+ * `claude -p` directly via services/fable-harness.ts (ADR-172's existing
+ * cost-disciplined harness) and caches the result for the insight ticker
+ * (funnel/insights.ts) to read synchronously.
+ */
+import { output } from '../output.js';
+import { hasConsent, recordConsent, revokeConsent } from '../funnel/consent.js';
+import { recordFunnelEvent } from '../funnel/events.js';
+import { getInstalledCliVersion } from '../init/helper-refresh.js';
+import { readAdvisorTip, ADVISOR_DEFAULT_BUDGET_USD } from '../funnel/advisor-tip.js';
+const ADVISOR_DISCLOSURE = [
+    'Enabling the co-pilot advisor tip.',
+    '',
+    'At most once per day, ruflo will send a small STRUCTURAL snapshot of your',
+    'session — security scan status, swarm/agent state, git uncommitted-file',
+    'COUNT — never raw prompts, file contents, or commands — to a headless',
+    'Fable model (via `claude -p`) and cache one short, actionable tip for the',
+    'statusline insight ticker.',
+    '',
+    `This is a real, metered API call (~$${ADVISOR_DEFAULT_BUDGET_USD.toFixed(2)} budget cap per`,
+    'refresh, at most once/day). Disable anytime: ruflo advisor disable',
+].join('\n');
+const enableSub = {
+    name: 'enable',
+    description: 'Opt into the co-pilot advisor tip (ADR-316)',
+    options: [
+        { name: 'yes', description: 'Skip the confirmation prompt', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        if (hasConsent('advisor-tips')) {
+            output.writeln('Advisor tip is already enabled.');
+            return { success: true, data: { alreadyEnabled: true } };
+        }
+        output.writeln(ADVISOR_DISCLOSURE);
+        output.writeln('');
+        if (!ctx.flags.yes) {
+            output.writeln('Re-run with --yes to confirm: ruflo advisor enable --yes');
+            return { success: true, data: { confirmed: false } };
+        }
+        recordConsent('advisor-tips', true, 'advisor-enable');
+        recordFunnelEvent('advisor_tip_enabled', 'statusline', getInstalledCliVersion());
+        output.printSuccess('Advisor tip enabled.');
+        output.writeln('It refreshes at most once/day, in the background, on session-restore.');
+        output.writeln('Disable anytime: ruflo advisor disable');
+        return { success: true, data: { confirmed: true } };
+    },
+};
+const disableSub = {
+    name: 'disable',
+    description: 'Revoke advisor-tip consent and stop generating new tips',
+    action: async () => {
+        revokeConsent('advisor-tips', 'advisor-disable');
+        recordFunnelEvent('advisor_tip_disabled', 'statusline', getInstalledCliVersion());
+        output.printSuccess('Advisor tip disabled.');
+        return { success: true };
+    },
+};
+const statusSub = {
+    name: 'status',
+    description: 'Show advisor-tip consent state and the current cached tip',
+    action: async () => {
+        const consented = hasConsent('advisor-tips');
+        output.writeln(`Advisor tip consent: ${consented ? 'granted' : 'not granted'}`);
+        const tip = consented ? readAdvisorTip() : null;
+        if (tip) {
+            output.writeln(`Current tip: ${tip.headline}`);
+            if (tip.detail)
+                output.writeln(`  ${tip.detail}`);
+        }
+        else if (consented) {
+            output.writeln('No cached tip yet (refreshes at most once/day on session-restore).');
+        }
+        return { success: true, data: { consented, tip } };
+    },
+};
+export const advisorCommand = {
+    name: 'advisor',
+    description: 'Fable co-pilot advisor tip in the statusline insight ticker (ADR-316)',
+    subcommands: [enableSub, disableSub, statusSub],
+    examples: [
+        { command: 'ruflo advisor enable --yes', description: 'Opt into the co-pilot advisor tip' },
+        { command: 'ruflo advisor status', description: 'Show consent state + current cached tip' },
+        { command: 'ruflo advisor disable', description: 'Revoke consent and stop generating tips' },
+    ],
+    action: statusSub.action,
+};
+export default advisorCommand;
+//# sourceMappingURL=advisor.js.map

package/dist/src/commands/doctor.js

@@ -135,8 +135,10 @@ async function checkConfigFile() {
  * the broken commands).
  */
 async function checkStaleSettingsNpx() {
-    // Same regex pattern the executor migration uses — kept in sync.
-    const BROKEN_RE = /npx\s+(?:--?\S+\s+)*@?claude-flow\/cli@latest\s+hooks\s+(?:statusline|\S+)/;
+    // Same regex pattern the executor migration uses — kept in sync. Flag-list
+    // repetition bounded at 10 (CodeQL js/redos — unbounded `*` here is
+    // exponential-backtracking-prone on a crafted settings.json).
+    const BROKEN_RE = /npx\s+(?:--?\S+\s+){0,10}@?claude-flow\/cli@latest\s+hooks\s+(?:statusline|\S+)/;
     // Look in both project-local and home-dir settings.
     const candidates = [
         join(process.cwd(), '.claude', 'settings.json'),
@@ -442,53 +444,98 @@ async function checkMcpServers() {
         '.mcp.json',
     ];
     const isRufloKey = (k) => k === 'ruflo' || k === 'ruflo_alpha' || k === 'claude-flow' || k === 'claude-flow_alpha';
+    // Canonical MCP-server key is `claude-flow` — matches the `mcp__claude-flow__*`
+    // prefix that ~166 plugin tool references depend on (#2206). A `ruflo`-keyed
+    // entry pointing at the same binary is the legacy duplicate created by
+    // pre-rename setup docs that #2612 tracks; doctor treats it as removable.
+    const isCurrentRufloKey = (k) => k === 'claude-flow' || k === 'claude-flow_alpha';
+    const isLegacyRufloKey = (k) => k === 'ruflo' || k === 'ruflo_alpha';
+    const isRufloServer = (server) => {
+        if (!server || typeof server !== 'object')
+            return false;
+        const entry = server;
+        const command = typeof entry.command === 'string' ? entry.command : '';
+        const args = Array.isArray(entry.args)
+            ? entry.args.filter((arg) => typeof arg === 'string')
+            : [];
+        const haystack = [command, ...args].join(' ');
+        return /\b(?:ruflo|claude-flow|@claude-flow\/cli)(?:@[\w.-]+)?\b/.test(haystack);
+    };
+    let totalServersSeen = 0;
+    const rufloLocations = [];
+    const duplicateLocations = [];
+    const legacyLocations = [];
+    const currentLocations = [];
+    const inspectServers = (servers, location) => {
+        if (!servers || typeof servers !== 'object')
+            return { total: 0, hasRuflo: false };
+        const entries = Object.entries(servers);
+        const activeRufloEntries = entries.filter(([key, server]) => isRufloKey(key) && isRufloServer(server));
+        const hasLegacy = activeRufloEntries.some(([key]) => isLegacyRufloKey(key));
+        const hasCurrent = activeRufloEntries.some(([key]) => isCurrentRufloKey(key));
+        if (activeRufloEntries.length > 0) {
+            rufloLocations.push(`${location}: ${activeRufloEntries.map(([key]) => key).join(', ')}`);
+        }
+        if (hasLegacy && hasCurrent) {
+            duplicateLocations.push(`${location}: ${activeRufloEntries.map(([key]) => key).join(' + ')}`);
+        }
+        for (const [key] of activeRufloEntries) {
+            if (isLegacyRufloKey(key))
+                legacyLocations.push(`${location}: ${key}`);
+            if (isCurrentRufloKey(key))
+                currentLocations.push(`${location}: ${key}`);
+        }
+        return { total: entries.length, hasRuflo: activeRufloEntries.length > 0 };
+    };
     for (const configPath of mcpConfigPaths) {
         if (!existsSync(configPath))
             continue;
         try {
             const content = JSON.parse(readFileSync(configPath, 'utf8'));
             // Top-level mcpServers (legacy / desktop form)
-            const topServers = content.mcpServers || content.servers || {};
-            const topServerKeys = Object.keys(topServers);
-            const topHasRuflo = topServerKeys.some(isRufloKey);
+            const topResult = inspectServers(content.mcpServers || content.servers || {}, `${configPath} top-level`);
+            totalServersSeen += topResult.total;
             // Project-scoped (Claude Code shape): projects[*].mcpServers.ruflo
-            let projectHits = 0;
-            let projectScannedServers = 0;
             if (content.projects && typeof content.projects === 'object') {
-                for (const projectVal of Object.values(content.projects)) {
+                for (const [projectKey, projectVal] of Object.entries(content.projects)) {
                     const pm = projectVal?.mcpServers;
                     if (pm && typeof pm === 'object') {
-                        const keys = Object.keys(pm);
-                        projectScannedServers += keys.length;
-                        if (keys.some(isRufloKey))
-                            projectHits += 1;
+                        const projectResult = inspectServers(pm, `${configPath} projects[${projectKey}]`);
+                        totalServersSeen += projectResult.total;
                     }
                 }
             }
-            const totalServers = topServerKeys.length + projectScannedServers;
-            if (topHasRuflo || projectHits > 0) {
-                const where = topHasRuflo
-                    ? 'top-level'
-                    : `${projectHits} project-scoped`;
-                return {
-                    name: 'MCP Servers',
-                    status: 'pass',
-                    message: `${totalServers} servers (ruflo configured: ${where})`,
-                };
-            }
-            if (totalServers > 0) {
-                return {
-                    name: 'MCP Servers',
-                    status: 'warn',
-                    message: `${totalServers} servers (ruflo not found)`,
-                    fix: 'claude mcp add ruflo -- npx -y ruflo@latest mcp start',
-                };
-            }
         }
         catch {
             // continue to next path
         }
     }
+    if (duplicateLocations.length > 0 || (legacyLocations.length > 0 && currentLocations.length > 0)) {
+        const locations = duplicateLocations.length > 0
+            ? duplicateLocations.join('; ')
+            : `legacy ${legacyLocations.join('; ')} + current ${currentLocations.join('; ')}`;
+        return {
+            name: 'MCP Servers',
+            status: 'warn',
+            message: `Duplicate Ruflo MCP registrations found (${locations}) — Claude Code will start both tool schemas`,
+            fix: 'Remove the legacy `ruflo`-keyed MCP registration (pre-rename duplicate) and keep the canonical `claude-flow` entry: `claude mcp add claude-flow -- npx -y ruflo@latest mcp start`. The canonical key stays `claude-flow` so the ~166 `mcp__claude-flow__*` plugin tool references keep resolving (#2206).',
+        };
+    }
+    if (rufloLocations.length > 0) {
+        return {
+            name: 'MCP Servers',
+            status: 'pass',
+            message: `${totalServersSeen} servers (ruflo configured: ${rufloLocations.join('; ')})`,
+        };
+    }
+    if (totalServersSeen > 0) {
+        return {
+            name: 'MCP Servers',
+            status: 'warn',
+            message: `${totalServersSeen} servers (ruflo not found)`,
+            fix: 'claude mcp add claude-flow -- npx -y ruflo@latest mcp start',
+        };
+    }
     return {
         name: 'MCP Servers',
         status: 'warn',
@@ -666,6 +713,74 @@ async function checkVersionFreshness() {
  *   - plugins/ruflo-metaharness/skills/harness-similarity/SKILL.md
  *   - plugins/ruflo-metaharness/skills/harness-drift-from-history/SKILL.md  (iter 53)
  */
+/**
+ * ADR-305 — funnel state audit. Reports the effective enabled/disabled
+ * state and, critically for enterprise audit verification, WHICH
+ * precedence source decided it (env > enterprise > user > default).
+ * Informational: both states are `pass`; only a resolver failure warns.
+ */
+async function checkFunnel() {
+    try {
+        const { resolveFunnelEnabled, getDisclosure } = await import('../funnel/index.js');
+        const decision = resolveFunnelEnabled();
+        const disclosure = getDisclosure();
+        return {
+            name: 'Funnel (ADR-305)',
+            status: 'pass',
+            message: `${decision.enabled ? 'enabled' : 'disabled'} (decided by: ${decision.decidedBy}; disclosure: ${disclosure.state})`,
+        };
+    }
+    catch (err) {
+        return {
+            name: 'Funnel (ADR-305)',
+            status: 'warn',
+            message: `state unreadable: ${err instanceof Error ? err.message : String(err)}`,
+            fix: 'ruflo funnel status',
+        };
+    }
+}
+/** Meta LLM Proxy — sponsored-downtime health (ADR-313). */
+async function checkProxy() {
+    try {
+        const { funnelStateDir, hasConsent, readRateLimitStatus, lastRecordedEvent } = await import('../funnel/index.js');
+        const dir = funnelStateDir();
+        const installed = existsSync(join(dir, 'proxy-token'));
+        const consented = hasConsent('sponsored-downtime');
+        const rateLimited = readRateLimitStatus();
+        const lastExhausted = lastRecordedEvent('sponsor_capacity_exhausted');
+        if (!installed) {
+            return {
+                name: 'Meta LLM Proxy (ADR-313)',
+                status: 'warn',
+                message: 'not installed — no proxy-token found; sponsored-downtime capacity is unavailable',
+                fix: 'See cognitum-one/meta-proxy (private) for install instructions',
+            };
+        }
+        const parts = [
+            `sponsored consent: ${consented ? 'granted' : 'not granted'}`,
+            `rate-limit flag: ${rateLimited.limited ? `set (since ${rateLimited.since})` : 'not set'}`,
+        ];
+        if (lastExhausted)
+            parts.push(`last capacity-exhausted: ${lastExhausted}`);
+        if (rateLimited.limited && !consented) {
+            return {
+                name: 'Meta LLM Proxy (ADR-313)',
+                status: 'warn',
+                message: `${parts.join('; ')} — flagged rate-limited but sponsored capacity isn't enabled`,
+                fix: 'ruflo proxy sponsor-enable --yes',
+            };
+        }
+        return { name: 'Meta LLM Proxy (ADR-313)', status: 'pass', message: parts.join('; ') };
+    }
+    catch (err) {
+        return {
+            name: 'Meta LLM Proxy (ADR-313)',
+            status: 'warn',
+            message: `state unreadable: ${err instanceof Error ? err.message : String(err)}`,
+            fix: 'ruflo proxy sponsor-status',
+        };
+    }
+}
 async function checkMetaharnessIntegration() {
     // Locate plugins dir.
     //
@@ -1042,7 +1157,7 @@ export const doctorCommand = {
         {
             name: 'component',
             short: 'c',
-            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, claude, disk, typescript, agentic-flow, encryption, federation, metaharness)',
+            description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, claude, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, metaharness)',
             type: 'string'
         },
         {
@@ -1092,6 +1207,8 @@ export const doctorCommand = {
             checkFederationBreaker, // ADR-097 Phase 4
             checkMetaharness, // ADR-150 — MetaHarness upstream package
             checkMetaharnessIntegration, // iter 45 — ruflo-side integration layer
+            checkFunnel, // ADR-305 — effective funnel state + deciding precedence source
+            checkProxy, // ADR-313 — Meta LLM Proxy sponsored-downtime health
         ];
         const componentMap = {
             'version': checkVersionFreshness,
@@ -1116,6 +1233,8 @@ export const doctorCommand = {
             'federation': checkFederationBreaker, // ADR-097 Phase 4
             'metaharness': checkMetaharness, // ADR-150 — upstream package
             'metaharness-integration': checkMetaharnessIntegration, // iter 45 — ruflo-side
+            'funnel': checkFunnel, // ADR-305
+            'proxy': checkProxy, // ADR-313
         };
         let checksToRun = allChecks;
         if (component && componentMap[component]) {

package/dist/src/commands/funnel.d.ts

@@ -0,0 +1,13 @@
+/**
+ * `ruflo funnel` — user control surface for the Cognitum lifecycle funnel
+ * (ADR-301/305/309).
+ *
+ *   funnel status    effective state and which precedence source decided it
+ *   funnel disable   user-level opt-out (all surfaces) + delete funnel data
+ *   funnel enable    re-enable at the user tier (cannot override env/enterprise)
+ *   funnel id        print the pseudonymous funnel ID, if one exists
+ */
+import type { Command } from '../types.js';
+export declare const funnelCommand: Command;
+export default funnelCommand;
+//# sourceMappingURL=funnel.d.ts.map

package/dist/src/commands/funnel.js

@@ -0,0 +1,103 @@
+/**
+ * `ruflo funnel` — user control surface for the Cognitum lifecycle funnel
+ * (ADR-301/305/309).
+ *
+ *   funnel status    effective state and which precedence source decided it
+ *   funnel disable   user-level opt-out (all surfaces) + delete funnel data
+ *   funnel enable    re-enable at the user tier (cannot override env/enterprise)
+ *   funnel id        print the pseudonymous funnel ID, if one exists
+ */
+import { output } from '../output.js';
+import { deleteFunnelData, funnelStateDir, getDisclosure, getFunnelId, readConsents, recordDisclosureDeclined, recordDisclosureReenabled, resolveFunnelEnabled, } from '../funnel/index.js';
+import { readStateJson, writeStateJson } from '../funnel/state.js';
+function setUserConfigEnabled(enabled) {
+    const cfg = readStateJson('funnel.json') ?? {};
+    cfg.enabled = enabled;
+    writeStateJson('funnel.json', cfg);
+}
+const statusSub = {
+    name: 'status',
+    description: 'Show effective funnel state and which source decided it',
+    options: [
+        { name: 'json', description: 'Output as JSON', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const decision = resolveFunnelEnabled();
+        const disclosure = getDisclosure();
+        const consents = readConsents();
+        const data = {
+            enabled: decision.enabled,
+            decidedBy: decision.decidedBy,
+            disclosure: disclosure.state,
+            stateDir: funnelStateDir(),
+            consents,
+        };
+        if (ctx.flags.json) {
+            output.printJson(data);
+        }
+        else {
+            output.writeln(`Funnel: ${decision.enabled ? 'enabled' : 'disabled'} (decided by: ${decision.decidedBy})`);
+            output.writeln(`Disclosure: ${disclosure.state}`);
+            output.writeln(`State dir: ${funnelStateDir()}`);
+            const domains = Object.keys(consents);
+            output.writeln(domains.length
+                ? `Consents: ${domains.map((d) => `${d}=${consents[d]?.granted ? 'granted' : 'declined'}`).join(', ')}`
+                : 'Consents: none recorded');
+        }
+        return { success: true, data };
+    },
+};
+const disableSub = {
+    name: 'disable',
+    description: 'Disable all funnel surfaces (user-level, persists across projects)',
+    action: async () => {
+        setUserConfigEnabled(false);
+        recordDisclosureDeclined();
+        deleteFunnelData(); // opt-out deletes the pseudonymous ID + local event queue
+        output.printSuccess('Funnel disabled. All promotional surfaces are off; local funnel data deleted.');
+        return { success: true };
+    },
+};
+const enableSub = {
+    name: 'enable',
+    description: 'Re-enable funnel surfaces at the user tier (env/enterprise disables still win)',
+    action: async () => {
+        setUserConfigEnabled(true);
+        recordDisclosureReenabled();
+        const decision = resolveFunnelEnabled();
+        if (decision.enabled) {
+            output.printSuccess('Funnel enabled.');
+        }
+        else {
+            // A lower-precedence source never overrides a higher-precedence disable.
+            output.printWarning(`User preference recorded, but the funnel stays disabled by a higher-precedence source: ${decision.decidedBy}`);
+        }
+        return { success: true, data: decision };
+    },
+};
+const idSub = {
+    name: 'id',
+    description: 'Print the pseudonymous funnel ID (exists only with telemetry consent)',
+    action: async () => {
+        const id = getFunnelId();
+        if (id) {
+            output.writeln(id);
+        }
+        else {
+            output.writeln('No funnel ID (telemetry consent not granted, or funnel data deleted).');
+        }
+        return { success: true, data: { id } };
+    },
+};
+export const funnelCommand = {
+    name: 'funnel',
+    description: 'Control the Cognitum lifecycle funnel surfaces (tips, enrollment, notices)',
+    subcommands: [statusSub, disableSub, enableSub, idSub],
+    examples: [
+        { command: 'ruflo funnel status', description: 'Effective state + deciding source' },
+        { command: 'ruflo funnel disable', description: 'Turn off every funnel surface' },
+    ],
+    action: statusSub.action,
+};
+export default funnelCommand;
+//# sourceMappingURL=funnel.js.map