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

fix: resolve current runtime and verification defects for v3.32.36 (#2850)

rUv67ff9898c0b7
diff --git a/.claude/helpers/hook-handler.cjs b/.claude/helpers/hook-handler.cjs
index 9615e71c00..b95cf1c308 100755
--- a/.claude/helpers/hook-handler.cjs
+++ b/.claude/helpers/hook-handler.cjs
@@ -89,9 +89,6 @@ function spawnDetachedHookRefresh(subcommand) {
detached: true,
stdio: 'ignore',
env: process.env,
- // Windows: without this, npx.cmd's cmd.exe wrapper flashes a visible
- // console window every time a hook fires a background refresh. Runs
- // hidden instead. No-op on POSIX.
windowsHide: true,
});
child.unref();
@@ -102,6 +99,105 @@ function spawnDetachedFunnelRefresh() {
spawnDetachedHookRefresh('refresh-funnel');
}
+// ADR-318/319: first-run auto-enable of spinner verbs (default ON) +
+// announcements (default OFF, explicit opt-in). Fires ONCE per install
+// (marker at ~/.ruflo/first-run-enabled.json), then never again β€”
+// subsequent sessions see the marker and skip.
+//
+// Split posture rationale:
+// - Spinner verbs = low-intrusion (per-spin flash, append-mode mix
+// with Claude Code defaults, moderate visibility over time). Default ON.
+// Disclosure notification + one-command disable satisfies the ethical bar.
+// - Announcements = higher-intrusion (prominent line at every Claude Code
+// startup, more attention per view). Default OFF; opt-in via
+// RUFLO_AUTO_ENABLE_ANNOUNCEMENTS=1 or explicit `ruflo announcements enable`.
+//
+// Gates (spinner is default-on unless any is TRUE):
+// - RUFLO_NO_AUTO_ENABLE truthy (master opt-out β€” kills both)
+// - RUFLO_NO_AUTO_ENABLE_SPINNER truthy (spinner-only opt-out)
+// - CI / GITHUB_ACTIONS truthy
+// - stdout is not a TTY (piped, non-interactive)
+// - Marker file already exists
+//
+// Announcements needs the same gates PLUS RUFLO_AUTO_ENABLE_ANNOUNCEMENTS=1.
+//
+// Marker is written even if the spawns fail β€” auto-enable is a "we tried once"
+// contract, not "keep trying until success." Users can run enable manually.
+function firstRunAutoEnableIfEligible() {
+ try {
+ const path = require('path');
+ const fs = require('fs');
+ const os = require('os');
+ const truthy = (v) => v && !/^(0|false|off|no)$/i.test(String(v));
+ if (truthy(process.env.RUFLO_NO_AUTO_ENABLE)) return;
+ if (process.env.CI || process.env.GITHUB_ACTIONS) return;
+ if (process.stdout && process.stdout.isTTY === false) return;
+ const markerPath = path.join(os.homedir(), '.ruflo', 'first-run-enabled.json');
+ if (fs.existsSync(markerPath)) return;
+
+ const enableSpinner = !truthy(process.env.RUFLO_NO_AUTO_ENABLE_SPINNER);
+ const enableAnnouncements = truthy(process.env.RUFLO_AUTO_ENABLE_ANNOUNCEMENTS);
+
+ // Nothing to do β€” user opted out of both. Skip marker write so if they
+ // change their mind and re-enable env vars later, first-run still fires.
+ if (!enableSpinner && !enableAnnouncements) return;
+
+ // Spawn the enable commands detached + non-blocking. Any failure
+ // (missing CLI, refused state, etc.) is silent β€” auto-enable is
+ // best-effort and MUST NOT block session-restore. Uses execPath +
+ // resolved cli.js directly rather than spawnDetachedHookRefresh
+ // because that helper hardcodes 'hooks' as the top-level command.
+ const { spawn } = require('child_process');
+ const cliBin = resolveCliBinForHook();
+ const runDetached = (args) => {
+ try {
+ const spawnArgs = cliBin
+ ? [process.execPath, [cliBin, ...args]]
+ : [process.platform === 'win32' ? 'npx.cmd' : 'npx',
+ ['--prefer-offline', '@claude-flow/cli', ...args]];
+ const child = spawn(spawnArgs[0], spawnArgs[1], {
+ detached: true, stdio: 'ignore', env: process.env, windowsHide: true,
+ });
+ child.unref();
+ } catch { /* best-effort */ }
+ };
+ if (enableSpinner) runDetached(['spinner', 'enable', '--yes']);
+ if (enableAnnouncements) runDetached(['announcements', 'enable', '--yes']);
+
+ try {
+ fs.mkdirSync(path.dirname(markerPath), { recursive: true, mode: 0o700 });
+ fs.writeFileSync(
+ markerPath,
+ JSON.stringify({
+ _ts: Date.now(),
+ source: 'session-restore-hook',
+ enabled: { spinner: enableSpinner, announcements: enableAnnouncements },
+ }, null, 2),
+ { encoding: 'utf-8', mode: 0o600 }
+ );
+ } catch { /* ignore β€” best effort */ }
+
+ // Notification tells user exactly what happened. stderr so it doesn't
+ // corrupt any downstream JSON stdout consumer.
+ try {
+ const parts = [];
+ if (enableSpinner) parts.push('spinner verbs');
+ if (enableAnnouncements) parts.push('startup announcements');
+ const disableCmds = [];
+ if (enableSpinner) disableCmds.push('`ruflo spinner disable`');
+ if (enableAnnouncements) disableCmds.push('`ruflo announcements disable`');
+ process.stderr.write(
+ '[ruflo] First-run: enabled ' + parts.join(' + ') + '. ' +
+ 'Disable anytime with ' + disableCmds.join(' / ') + '. ' +
+ (enableSpinner && !enableAnnouncements
+ ? 'Announcements stay opt-in β€” set RUFLO_AUTO_ENABLE_ANNOUNCEMENTS=1 to enable those too. '
+ : '') +
+ 'Restart Claude Code once to see the changes take effect.\n'
+ );
+ } catch { /* ignore */ }
+ } catch { /* auto-enable must never break session-restore */ }
+}
+
// Same fallback-aware pattern as spawnDetachedFunnelRefresh() above, for
// ADR-316's co-pilot advisor tip. Safe to call on EVERY session-restore:
// refresh-advisor's own action checks consent + a 24h TTL BEFORE spending
@@ -190,6 +286,31 @@ async function readStdin() {
});
}
+function claimSideEffectEvent(family, stdinData, event) {
+ if (/^(1|true|yes|on)$/i.test(process.env.RUFLO_DISABLE_HOOK_DEDUP || '')) return true;
+ try {
+ const crypto = require('crypto');
+ const eventId = event?.tool_use_id || event?.toolUseId ||
+ event?.session_id || event?.sessionId || event?.hook_event_id;
+ const payloadIdentity = eventId
+ ? `event:${eventId}`
+ : `payload:${(stdinData || '').trim()}|bucket:${Math.floor(Date.now() / 2000)}`;
+ const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+ const digest = crypto.createHash('sha256')
+ .update(`ruflo-hook-dedup-v1\0${path.resolve(projectRoot)}\0${family}\0${payloadIdentity}`)
+ .digest('hex');
+ const dir = process.env.RUFLO_HOOK_DEDUP_DIR ||
+ path.join(os.tmpdir(), 'ruflo-hook-dedup-v1');
+ fs.mkdirSync(dir, { recursive: true });
+ const fd = fs.openSync(path.join(dir, digest), 'wx', 0o600);
+ fs.writeFileSync(fd, String(Date.now()));
+ fs.closeSync(fd);
+ return true;
+ } catch (error) {
+ return error?.code === 'EEXIST' ? false : true;
+ }
+}
+
async function main() {
// Global safety timeout: hooks must NEVER hang (#1530, #1531)
const safetyTimer = setTimeout(() => {
@@ -206,6 +327,11 @@ async function main() {
try { hookInput = JSON.parse(stdinData); } catch (e) { /* ignore parse errors */ }
}
+ if ((command === 'post-edit' || command === 'session-end') &&
+ !claimSideEffectEvent(command, stdinData, hookInput)) {
+ return;
+ }
+
// Normalize snake_case/camelCase: Claude Code sends tool_input/tool_name (snake_case)
const toolInput = hookInput.toolInput || hookInput.tool_input || {};
const toolName = hookInput.toolName || hookInput.tool_name || '';
@@ -349,6 +475,11 @@ const handlers = {
},
'session-restore': async () => {
+ // ADR-318/319 first-run auto-enable β€” fire once per install, never
+ // re-fires after user disables. Respects RUFLO_NO_AUTO_ENABLE + CI.
+ // Fully non-blocking (detached spawn) so session-restore latency
+ // is unchanged.
+ firstRunAutoEnableIfEligible();
if (session) {
// Try restore first, fall back to start
const existing = session.restore && session.restore();
diff --git a/.claude/helpers/intelligence.cjs b/.claude/helpers/intelligence.cjs
index 5f3d6d3905..cd6e720c84 100755
--- a/.claude/helpers/intelligence.cjs
+++ b/.claude/helpers/intelligence.cjs
@@ -17,12 +17,30 @@
const fs = require('fs');
const path = require('path');
-const DATA_DIR = path.join(process.cwd(), '.claude-flow', 'data');
+function resolveProjectRoot(startDir) {
+ if (process.env.CLAUDE_PROJECT_DIR) {
+ return path.resolve(process.env.CLAUDE_PROJECT_DIR);
+ }
+ let dir = path.resolve(startDir || process.cwd());
+ while (true) {
+ if (fs.existsSync(path.join(dir, '.git')) ||
+ fs.existsSync(path.join(dir, '.claude-flow'))) {
+ return dir;
+ }
+ const parent = path.dirname(dir);
+ if (parent === dir) return path.resolve(startDir || process.cwd());
+ dir = parent;
+ }
+}
+
+const PROJECT_ROOT = resolveProjectRoot(process.cwd());
+const DATA_DIR = path.join(PROJECT_ROOT, '.claude-flow', 'data');
const STORE_PATH = path.join(DATA_DIR, 'auto-memory-store.json');
const GRAPH_PATH = path.join(DATA_DIR, 'graph-state.json');
const RANKED_PATH = path.join(DATA_DIR, 'ranked-context.json');
const PENDING_PATH = path.join(DATA_DIR, 'pending-insights.jsonl');
-const SESSION_DIR = path.join(process.cwd(), '.claude-flow', 'sessions');
+const LEGACY_PENDING_PATH = path.join(process.cwd(), '.claude-flow', 'data', 'pending-insights.jsonl');
+const SESSION_DIR = path.join(PROJECT_ROOT, '.claude-flow', 'sessions');
const SESSION_FILE = path.join(SESSION_DIR, 'current.json');
// ── Safety limits (fixes #1530, #1531) ─────────────────────────────────────
@@ -47,6 +65,22 @@ const STOP_WORDS = new Set([
function ensureDataDir() {
if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+ // Recover signal written by older helpers under a subdirectory cwd. Keep
+ // the legacy file intact and append only lines not already present.
+ if (path.resolve(LEGACY_PENDING_PATH) !== path.resolve(PENDING_PATH) &&
+ fs.existsSync(LEGACY_PENDING_PATH)) {
+ try {
+ const existing = fs.existsSync(PENDING_PATH)
+ ? new Set(fs.readFileSync(PENDING_PATH, 'utf-8').split('\n').filter(Boolean))
+ : new Set();
+ const recovered = fs.readFileSync(LEGACY_PENDING_PATH, 'utf-8')
+ .split('\n')
+ .filter(line => line && !existing.has(line));
+ if (recovered.length > 0) {
+ fs.appendFileSync(PENDING_PATH, recovered.join('\n') + '\n', 'utf-8');
+ }
+ } catch { /* migration is best-effort; never block hook execution */ }
+ }
}
function readJSON(filePath) {
@@ -300,7 +334,7 @@ function buildEdges(entries) {
*/
function bootstrapFromMemoryFiles() {
const entries = [];
- const cwd = process.cwd();
+ const cwd = PROJECT_ROOT;
// Search for auto-memory directories
const candidates = [
@@ -1032,7 +1066,16 @@ function stats(outputJson) {
return report;
}
-module.exports = { init, getContext, recordEdit, feedback, consolidate, stats };
+module.exports = {
+ init,
+ getContext,
+ recordEdit,
+ feedback,
+ consolidate,
+ stats,
+ resolveProjectRoot,
+ projectRoot: PROJECT_ROOT,
+};
// ── CLI entrypoint ──────────────────────────────────────────────────────────
if (require.main === module) {
diff --git a/.github/workflows/helpers-manifest-guard.yml b/.github/workflows/helpers-manifest-guard.yml
index 0635b57a7f..565d8ebf09 100644
--- a/.github/workflows/helpers-manifest-guard.yml
+++ b/.github/workflows/helpers-manifest-guard.yml
@@ -20,6 +20,7 @@ on:
- 'v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json'
- 'v3/@claude-flow/cli/scripts/sign-helpers.mjs'
- 'v3/@claude-flow/cli/scripts/verify-helpers.mjs'
+ - 'scripts/smoke-helper-signing-security.mjs'
- 'v3/@claude-flow/cli/scripts/prepare-publish.mjs'
- 'v3/@claude-flow/cli/package.json'
- '.github/workflows/helpers-manifest-guard.yml'
@@ -29,6 +30,7 @@ on:
- 'v3/@claude-flow/cli/.claude/helpers/**'
- 'v3/@claude-flow/cli/scripts/sign-helpers.mjs'
- 'v3/@claude-flow/cli/scripts/verify-helpers.mjs'
+ - 'scripts/smoke-helper-signing-security.mjs'
- 'v3/@claude-flow/cli/scripts/prepare-publish.mjs'
- 'v3/@claude-flow/cli/package.json'
@@ -50,6 +52,9 @@ jobs:
test -f v3/@claude-flow/cli/scripts/sign-helpers.mjs || { echo '::error::scripts/sign-helpers.mjs missing (#2593)'; exit 1; }
test -f v3/@claude-flow/cli/scripts/verify-helpers.mjs || { echo '::error::scripts/verify-helpers.mjs missing (#2593)'; exit 1; }
+ - name: Helper signing key transport + single-source guard
+ run: node scripts/smoke-helper-signing-security.mjs
+
# 2. prepublishOnly MUST invoke a preparation script that invokes BOTH
# sign-helpers and verify-helpers.
# This is the exact regression from #2593 β€” sign existed but was
diff --git a/CLAUDE.md b/CLAUDE.md
index 2fd7e15842..c8c0219430 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -994,18 +994,19 @@ RUFLO_HELPERS_SIGNING_SECRET=ruflo-helpers-signing-key RUFLO_HELPERS_SIGNING_PRO
(`ruv-dev` also holds `ruflo-config-signing-key`; do not replace the existing
authenticated npm session with a token from another project.)
-**Handling the signing key without leaking it (learned 2026-07-14, hard way):** when
-sign-helpers.mjs runs via `execFileSync('gcloud', ...)` on Windows, Node fails to find
-`gcloud` (needs the `.cmd` suffix), so the script bails and users reach for
-`gcloud secrets versions access latest --secret=ruflo-helpers-signing-key` in the shell β€”
-which by default prints the PEM to stdout, which becomes tool-call output in Claude
-Code and lands in the session transcript. That happened, the key was leaked, GCP secret
-v1 was destroyed and a fresh v2 was rotated in (commit 0052b1b06 / PR #2673). **Rules:**
+**Handling the signing key without leaking it (learned 2026-07-14, hard way):**
+an earlier Windows path invoked `gcloud` without its required `.cmd` suffix. The
+fallback command printed the PEM into captured tool output and a session transcript.
+GCP secret v1 was destroyed and a fresh v2 was rotated in (commit 0052b1b06 /
+PR #2673). `sign-helpers.mjs` now selects `gcloud.cmd` on Windows and supports a
+stdin-only fallback. **Rules:**
- NEVER invoke `gcloud secrets versions access` in a way that lets the payload reach
- tool output. Always redirect to a file in the same command: `gcloud … > ~/.ruflo/helpers-signing.key 2>&1 | grep -v BEGIN`.
-- On Windows, prefer `RUFLO_HELPERS_SIGNING_KEY=~/.ruflo/helpers-signing.key` over the
- GCP env var, because the fallback file path doesn't go through the broken
- `execFileSync('gcloud')` path.
+ tool output. Use the built-in `RUFLO_HELPERS_SIGNING_SECRET` path above, or pipe
+ directly into the signer:
+ `gcloud secrets versions access latest --secret=ruflo-helpers-signing-key --project=ruv-dev | node scripts/sign-helpers.mjs --stdin-key`.
+- `--stdin-key` refuses interactive entry, validates Ed25519 key type, and never
+ echoes parser input. A local file via `RUFLO_HELPERS_SIGNING_KEY` remains the
+ air-gapped fallback.
- If a rotation IS needed, keep the private half in `~/.ruflo/helpers-signing.key`
only, print ONLY the public half (via `Ed25519 pub export` from Node crypto), upload
new private via `gcloud secrets versions add … --data-file=`, then
diff --git a/package-lock.json b/package-lock.json
index f107565594..4c25e08f51 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "claude-flow",
- "version": "3.32.35",
+ "version": "3.32.36",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "claude-flow",
- "version": "3.32.35",
+ "version": "3.32.36",
"bundleDependencies": [
"@claude-flow/codex",
"@claude-flow/plugin-agent-federation",
diff --git a/package.json b/package.json
index 43de49c7ed..548dad2964 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
{
"name": "claude-flow",
- "version": "3.32.35",
+ "version": "3.32.36",
"workspaces": [
"v3/@claude-flow/codex",
"v3/@claude-flow/plugin-agent-federation",
diff --git a/plugins/ruflo-core/.claude-plugin/plugin.json b/plugins/ruflo-core/.claude-plugin/plugin.json
index fb444b1cd4..561451c6cb 100644
--- a/plugins/ruflo-core/.claude-plugin/plugin.json
+++ b/plugins/ruflo-core/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-core",
- "description": "Foundation plugin β€” registers the ruflo MCP server (300+ tools across memory/agentdb/embeddings/hooks/aidefence/neural/autopilot/browser/agent/swarm), provides 4 generalist agents (coder/researcher/reviewer/witness-curator), 4 first-run skills (discover-plugins/init-project/ruflo-doctor/witness), and a curated plugin-discovery catalog",
- "version": "0.2.4",
+ "description": "Foundation plugin β€” registers the ruflo MCP server (300+ tools across memory/agentdb/embeddings/hooks/aidefence/neural/autopilot/browser/agent/swarm), provides 4 generalist agents (coder/researcher/reviewer/witness-curator), 5 skills (discover-plugins/init-project/ruflo-doctor/ruflo-status/witness), and a curated plugin-discovery catalog",
+ "version": "0.2.5",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-core/commands/witness.md b/plugins/ruflo-core/commands/witness.md
index 5d218fbbf3..831d1a455e 100644
--- a/plugins/ruflo-core/commands/witness.md
+++ b/plugins/ruflo-core/commands/witness.md
@@ -21,6 +21,10 @@ node plugins/ruflo-core/scripts/witness/regen.mjs \
# Verify against live tree
node plugins/ruflo-core/scripts/witness/verify.mjs --manifest verification.md.json
+# Verify without dependencies or generated dist/ artifacts
+node plugins/ruflo-core/scripts/witness/verify.mjs \
+ --manifest verification.md.json --source-only
+
# Temporal queries
node plugins/ruflo-core/scripts/witness/history.mjs --history verification-history.jsonl summary
node plugins/ruflo-core/scripts/witness/history.mjs --history verification-history.jsonl regressions
diff --git a/plugins/ruflo-core/docs/adrs/0001-core-contract.md b/plugins/ruflo-core/docs/adrs/0001-core-contract.md
index e9aea8f0b5..52c31695f1 100644
--- a/plugins/ruflo-core/docs/adrs/0001-core-contract.md
+++ b/plugins/ruflo-core/docs/adrs/0001-core-contract.md
@@ -3,7 +3,7 @@ id: ADR-0001
title: ruflo-core plugin contract β€” pinning, MCP server contract, plugin-catalog discovery, smoke as contract
status: Accepted
date: 2026-05-04
-updated: 2026-05-09
+updated: 2026-07-29
authors:
- reviewer (Claude Code)
tags: [plugin, core, mcp, foundation, smoke-test]
@@ -13,14 +13,15 @@ tags: [plugin, core, mcp, foundation, smoke-test]
`ruflo-core` is the **foundation plugin**. Every other plugin (`ruflo-ruvector`, `ruflo-agentdb`, `ruflo-browser`, `ruflo-intelligence`, `ruflo-adr`, `ruflo-aidefence`, `ruflo-autopilot`, plus 25 others) depends on the MCP server it registers via `.mcp.json` and the orchestration patterns it documents.
-Today's plugin (v0.1.0):
+The current plugin contract (v0.2.5):
-- `.claude-plugin/plugin.json:4` β€” `version: "0.1.0"`, keywords `mcp, orchestration, claude-code`
+- `.claude-plugin/plugin.json` β€” `version: "0.2.5"`, foundation and discovery metadata
- `.mcp.json` β€” registers `ruflo` MCP server via `npx -y @claude-flow/cli@latest`
-- `agents/` β€” 3 generalists (`coder`, `researcher`, `reviewer`)
-- `skills/` β€” 3 first-run helpers (`init-project`, `ruflo-doctor`, `discover-plugins`)
-- `commands/ruflo-status.md` β€” system status one-liner
-- `README.md` β€” terse: "What's Included" + Configuration only
+- `agents/` β€” 4 generalists (`coder`, `researcher`, `reviewer`, `witness-curator`)
+- `skills/` β€” 5 native skills (`init-project`, `ruflo-doctor`, `ruflo-status`, `discover-plugins`, `witness`)
+- `commands/` β€” Claude commands for `ruflo-status` and `witness`, each paired with a same-name Codex skill
+- `README.md` β€” documents installation, compatibility, MCP contract, sibling
+ contracts, architecture decisions, and verification
The discover-plugins skill is a substantial asset β€” a curated 32-plugin catalog with decision guides. That stays.
@@ -34,7 +35,7 @@ What's missing matches the cadence we've established:
## Decision
-### 1. Add this ADR (Proposed)
+### 1. Maintain this ADR (Accepted)
`docs/adrs/0001-core-contract.md`. Cross-links the seven sibling ADRs.
@@ -53,18 +54,30 @@ Append:
### 4. Smoke contract (`scripts/smoke.sh`)
-10 checks:
+11 checks:
-1. plugin.json declares `0.2.0` with the new keywords.
+1. plugin.json declares `0.2.5` with the foundation keywords.
2. `.mcp.json` exists and registers a `ruflo` MCP server.
-3. All 3 agents present (`coder`, `researcher`, `reviewer`) with valid frontmatter.
-4. All 3 skills present (`init-project`, `ruflo-doctor`, `discover-plugins`) with valid frontmatter.
+3. All 4 agents are present with valid frontmatter.
+4. All 5 skills are present with valid frontmatter.
5. `discover-plugins` skill catalog references at least 25 sibling plugins (the curated catalog).
6. README pins to `@claude-flow/cli` v3.6.
7. README cross-references sibling contracts (namespace convention, 3-gate pattern, 4-step pipeline).
-8. ADR-0001 exists with status `Proposed`.
+8. ADR-0001 exists with status `Accepted`.
9. `commands/ruflo-status.md` invokes `doctor` and `status`.
10. No skill grants wildcard tool access.
+11. Every Claude command has a same-name Codex skill or a documented explicit exemption.
+
+### 5. Cross-host hook and command compatibility
+
+- PreToolUse telemetry always runs.
+- Cursor retains its `{"permission":"allow"}` response.
+- Codex plugin hooks are positively detected through Codex-specific
+ `PLUGIN_ROOT` / `PLUGIN_DATA` variables and allow with exit 0 plus empty
+ stdout, avoiding an invalid bare permission object.
+- `/ruflo-status` remains unchanged for Claude Code. Codex discovers the
+ same workflow through `skills/ruflo-status/SKILL.md`: run `doctor`, then
+ `status`; run `doctor --fix` only after an explicit repair request.
## Consequences
@@ -77,13 +90,14 @@ Append:
- `discover-plugins` catalog must be kept in sync as plugins are added. Today there are 33 plugins (including this one); the catalog covers ~32. Drift remediation is a separate, mechanical task.
**Neutral:**
-- No new MCP tools, no new skills, no new agents. Documentation + smoke only.
+- No new MCP tools or agents. The status skill exposes an existing command
+ workflow to Codex without changing the Claude command.
## Verification
```bash
bash plugins/ruflo-core/scripts/smoke.sh
-# Expected: "10 passed, 0 failed"
+# Expected: "11 passed, 0 failed"
```
## Related
@@ -99,4 +113,4 @@ bash plugins/ruflo-core/scripts/smoke.sh
## Implementation status
-Plugin version v0.2.1 shipped and listed in marketplace.json. Source exists at `plugins/ruflo-core/`. Contract elements implemented: `.mcp.json` registers `ruflo` server via `npx -y @claude-flow/cli@latest`; plugin-catalog discovery skill present; 3 generalist agents shipped; smoke-as-contract gate defined in `scripts/smoke.sh`.
+Plugin source version v0.2.5 is listed by path in `.claude-plugin/marketplace.json`, so the marketplace artifact includes the five native skills and host-aware hook shim. Contract elements implemented: `.mcp.json` registers the `ruflo` server via `npx -y @claude-flow/cli@latest`; plugin-catalog discovery and Codex-native status skills are present; four generalist agents ship; command/skill parity and the remaining inventory are enforced by `scripts/smoke.sh`.
diff --git a/plugins/ruflo-core/hooks/hooks.json b/plugins/ruflo-core/hooks/hooks.json
index 3c51181b6d..3f922b9cfd 100644
--- a/plugins/ruflo-core/hooks/hooks.json
+++ b/plugins/ruflo-core/hooks/hooks.json
@@ -1,5 +1,5 @@
{
- "_note": "#1921/#2613/#2721 β€” hook commands invoke scripts/ruflo-hook.cjs (resilient shim): prefers a locally-installed `ruflo`/`claude-flow` binary, falls back to `npx --prefer-offline`, and always exits 0 so a CLI/install failure (e.g. arborist `Invalid Version` on npm 10.8.x) never surfaces an error in Claude Code or blocks a turn. PreToolUse commands additionally echo a valid `{\"permission\":\"allow\"}` verdict on stdout: Claude Code ignores it (JSON-shaped stdout is still valid), while Cursor (which imports third-party hooks under its stricter preToolUse contract and requires JSON-verdict stdout) receives a well-formed permission response and does not fail-closed. DO NOT revert to a bare `npx <pkg>@alpha hooks …` per fire.",
+ "_note": "#1921/#2613/#2721/#2816 β€” hook commands invoke scripts/ruflo-hook.cjs (resilient shim): prefers a locally-installed `ruflo`/`claude-flow` binary, falls back to `npx --prefer-offline`, and always exits 0 so a CLI/install failure (e.g. arborist `Invalid Version` on npm 10.8.x) never surfaces an error or blocks a turn. PreToolUse commands emit Cursor's valid `{\"permission\":\"allow\"}` verdict except when Codex's plugin-only PLUGIN_ROOT/PLUGIN_DATA variables are present; Codex unconditional allow is exit 0 with empty stdout. Telemetry runs in both paths. DO NOT revert to a bare `npx <pkg>@alpha hooks …` per fire.",
"_platform_note": "#2721 β€” every command below is a `node -e` bootstrap: it resolves this plugin's scripts/ruflo-hook.cjs from process.env.CLAUDE_PLUGIN_ROOT INSIDE Node (no shell `${VAR}`/`%VAR%` expansion, so the exact same command string runs unchanged on Windows, macOS, and Linux), then requires it with process.argv pre-seeded for the target subcommand. No bash, sh, cmd.exe, jq, or .sh scripts are involved.",
"hooks": {
"PreToolUse": [
diff --git a/plugins/ruflo-core/scripts/fixtures/hook-cli-recorder.cjs b/plugins/ruflo-core/scripts/fixtures/hook-cli-recorder.cjs
new file mode 100644
index 0000000000..8749250b75
--- /dev/null
+++ b/plugins/ruflo-core/scripts/fixtures/hook-cli-recorder.cjs
@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+'use strict';
+
+// Execution fixture for test-hooks.mjs. The hook shim invokes CLI commands as
+// `<cli> hooks <subcommand> ...`; surfacing that subcommand proves telemetry
+// was attempted without coupling the host-protocol regression to CLI startup.
+const [, , group, subcommand] = process.argv;
+if (group !== 'hooks' || !subcommand) process.exit(2);
+process.stdout.write(`hook-telemetry:${subcommand}`);
diff --git a/plugins/ruflo-core/scripts/ruflo-hook.cjs b/plugins/ruflo-core/scripts/ruflo-hook.cjs
index 7e2dd5c80a..f91db2fb67 100644
--- a/plugins/ruflo-core/scripts/ruflo-hook.cjs
+++ b/plugins/ruflo-core/scripts/ruflo-hook.cjs
@@ -11,8 +11,10 @@
* every OS (see the `node -e` bootstrap command in ../hooks/hooks.json).
* It replicates, in pure Node with no shell/jq dependency:
* - modify-bash / modify-file (PreToolUse) β€” best-effort CLI call, then
- * ALWAYS echo `{"permission":"allow"}` on stdout (Cursor's PreToolUse
- * contract requires valid-JSON stdout; Claude Code ignores it).
+ * emit `{"permission":"allow"}` for Cursor/Claude compatibility. Codex
+ * plugin hooks are detected by their Codex-specific PLUGIN_ROOT /
+ * PLUGIN_DATA variables and intentionally receive empty stdout: a bare
+ * Cursor permission object is not valid Codex hook JSON (#2816).
* - post-command / post-edit (PostToolUse) β€” parse the hook event JSON
* from stdin (no jq), extract the same fields the bash version pulled
* with jq, and forward them as CLI flags.
@@ -37,6 +39,9 @@
const { spawnSync, execSync } = require('child_process');
const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
/** Exit 0 unconditionally β€” hooks must never block a turn */
function done() {
@@ -165,6 +170,46 @@ function parseEventJson(stdinData) {
}
}
+/**
+ * Project-installed hooks and marketplace-plugin hooks can receive the same
+ * event. Claim side-effecting events atomically so post-edit learning and
+ * session-end consolidation execute exactly once (#2640).
+ */
+function claimSideEffectEvent(family, stdinData, event) {
+ if (/^(1|true|yes|on)$/i.test(process.env.RUFLO_DISABLE_HOOK_DEDUP || '')) return true;
+ try {
+ const eventId = event?.tool_use_id || event?.toolUseId ||
+ event?.session_id || event?.sessionId || event?.hook_event_id;
+ const payloadIdentity = eventId
+ ? `event:${eventId}`
+ : `payload:${(stdinData || '').trim()}|bucket:${Math.floor(Date.now() / 2000)}`;
+ const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+ const digest = crypto.createHash('sha256')
+ .update(`ruflo-hook-dedup-v1\0${path.resolve(projectRoot)}\0${family}\0${payloadIdentity}`)
+ .digest('hex');
+ const dir = process.env.RUFLO_HOOK_DEDUP_DIR ||
+ path.join(os.tmpdir(), 'ruflo-hook-dedup-v1');
+ fs.mkdirSync(dir, { recursive: true });
+ const fd = fs.openSync(path.join(dir, digest), 'wx', 0o600);
+ fs.writeFileSync(fd, String(Date.now()));
+ fs.closeSync(fd);
+ return true;
+ } catch (error) {
+ return error?.code === 'EEXIST' ? false : true;
+ }
+}
+
+/**
+ * Codex sets PLUGIN_ROOT and PLUGIN_DATA for plugin-bundled hooks, in
+ * addition to the cross-host CLAUDE_PLUGIN_* compatibility variables.
+ * Cursor and Claude Code use CLAUDE_PLUGIN_ROOT without these Codex-specific
+ * variables. Keep this positive Codex check narrow so existing Cursor
+ * installations retain their permission response.
+ */
+function isCodexPluginHost() {
+ return Boolean(process.env.PLUGIN_ROOT || process.env.PLUGIN_DATA);
+}
+
/**
* PreCompact guidance text β€” matches the bash `echo` lines verbatim.
* Not a CLI call at all; pure stdout guidance for the transcript/context.
@@ -214,10 +259,15 @@ function main() {
}
const stdinData = readStdinRaw();
+ const event = parseEventJson(stdinData);
+
+ if ((subcommand === 'post-edit' || subcommand === 'session-end') &&
+ !claimSideEffectEvent(subcommand, stdinData, event)) {
+ done();
+ }
// PostToolUse: derive CLI flags from the hook event JSON (replaces jq).
if (subcommand === 'post-command') {
- const event = parseEventJson(stdinData);
const cmd = event?.tool_input?.command;
if (!cmd) done(); // bash version: `[ -z "$CMD" ] && exit 0`
const exitCode = event?.tool_response?.exit_code ?? 0;
@@ -225,18 +275,19 @@ function main() {
done();
}
if (subcommand === 'post-edit') {
- const event = parseEventJson(stdinData);
const file = event?.tool_input?.file_path ?? event?.tool_input?.path;
if (!file) done(); // bash version: `[ -z "$FILE" ] && exit 0`
invokeCli('post-edit', ['-f', String(file), '-s', 'true'], stdinData);
done();
}
- // PreToolUse: best-effort CLI call, then ALWAYS echo the permission verdict
- // (Cursor's stricter preToolUse contract requires valid-JSON stdout).
+ // PreToolUse: telemetry always runs. Cursor retains its permission verdict;
+ // Codex unconditional allow is exit 0 with empty stdout (#2816).
if (subcommand === 'modify-bash' || subcommand === 'modify-file') {
invokeCli(subcommand, [], stdinData);
- process.stdout.write('{"permission":"allow"}');
+ if (!isCodexPluginHost()) {
+ process.stdout.write('{"permission":"allow"}');
+ }
done();
}
diff --git a/plugins/ruflo-core/scripts/smoke.sh b/plugins/ruflo-core/scripts/smoke.sh
index 349004f570..df28a76775 100755
--- a/plugins/ruflo-core/scripts/smoke.sh
+++ b/plugins/ruflo-core/scripts/smoke.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Structural smoke test for ruflo-core v0.2.4 (ADR-0001).
+# Structural smoke test for ruflo-core v0.2.5 (ADR-0001).
set -u
ROOT="$(cd "$(dirname "$0")/.." && pwd)"
PASS=0
@@ -8,10 +8,10 @@ step() { printf "β†’ %s ... " "$1"; }
ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
-step "1. plugin.json declares 0.2.4 with new keywords"
+step "1. plugin.json declares 0.2.5 with new keywords"
v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.2.4" ]]; then
- bad "expected 0.2.4, got '$v'"
+if [[ "$v" != "0.2.5" ]]; then
+ bad "expected 0.2.5, got '$v'"
else
miss=""
for k in foundation mcp-server plugin-catalog discovery; do
@@ -28,9 +28,9 @@ else
bad ".mcp.json missing or no ruflo server registration"
fi
-step "3. all 3 agents present with valid frontmatter"
+step "3. all 4 agents present with valid frontmatter"
miss=""
-for a in coder researcher reviewer; do
+for a in coder researcher reviewer witness-curator; do
f="$ROOT/agents/$a.md"
[[ -f "$f" ]] || { miss="$miss missing-$a"; continue; }
for k in 'name:' 'description:'; do
@@ -39,9 +39,9 @@ for a in coder researcher reviewer; do
done
[[ -z "$miss" ]] && ok || bad "$miss"
-step "4. all 3 skills present with valid frontmatter"
+step "4. all 5 skills present with valid frontmatter"
miss=""
-for s in init-project ruflo-doctor discover-plugins; do
+for s in init-project ruflo-doctor ruflo-status discover-plugins witness; do
f="$ROOT/skills/$s/SKILL.md"
[[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
for k in 'name:' 'description:' 'allowed-tools:'; do
@@ -91,5 +91,20 @@ for f in "$ROOT"/skills/*/SKILL.md; do
done
[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
+step "11. every Claude command has a same-name Codex skill"
+miss=""
+# Explicit exemptions must be recorded here as "command: reason". None exist.
+command_skill_exemptions=()
+for command_file in "$ROOT"/commands/*.md; do
+ command_name="$(basename "$command_file" .md)"
+ [[ -f "$ROOT/skills/$command_name/SKILL.md" ]] && continue
+ exempt=""
+ for entry in "${command_skill_exemptions[@]}"; do
+ [[ "$entry" == "$command_name: "* ]] && exempt="$entry"
+ done
+ [[ -n "$exempt" ]] || miss="$miss $command_name"
+done
+[[ -z "$miss" ]] && ok || bad "commands missing same-name skills:$miss"
+
printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-core/scripts/test-hooks.mjs b/plugins/ruflo-core/scripts/test-hooks.mjs
index 3e65b875c9..dabbf93696 100644
--- a/plugins/ruflo-core/scripts/test-hooks.mjs
+++ b/plugins/ruflo-core/scripts/test-hooks.mjs
@@ -1,6 +1,6 @@
#!/usr/bin/env node
/**
- * Regression guard for ruvnet/ruflo#1859, #1862, #2721.
+ * Regression guard for ruvnet/ruflo#1859, #1862, #2721, #2816.
*
* Drives every hook command from `hooks/hooks.json` β€” PreToolUse,
* PostToolUse, PreCompact, Stop β€” with synthetic Claude-Code-style stdin,
@@ -24,8 +24,9 @@
* - Exit code 0 (no parser errors like "Invalid value for --format")
* - Output records the *intended* value (the file path / command), not a
* stray boolean like "true" β€” the symptom that #1859 reported
- * - PreToolUse hooks always emit valid `{"permission":"allow"}` JSON on
- * stdout (Cursor's stricter PreToolUse contract, #2613)
+ * - Cursor PreToolUse hooks emit valid `{"permission":"allow"}` JSON
+ * - Codex PreToolUse hooks exit 0 with empty stdout, while both telemetry
+ * subcommands are still invoked (#2816)
* - PostToolUse hooks silently no-op (exit 0, no CLI call) when the
* expected field is missing from the event JSON
* - Malformed / empty stdin never causes a nonzero exit
@@ -37,14 +38,16 @@
* (windows-latest, macos-latest, ubuntu-latest).
*/
-import { readFileSync } from 'node:fs';
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs';
import { spawnSync } from 'node:child_process';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
+import { tmpdir } from 'node:os';
const __dirname = dirname(fileURLToPath(import.meta.url));
const PLUGIN_ROOT = join(__dirname, '..');
const HOOKS_JSON = join(PLUGIN_ROOT, 'hooks', 'hooks.json');
+const HOOK_RECORDER = join(__dirname, 'fixtures', 'hook-cli-recorder.cjs');
// `cliInvoke` is the literal token-string that should run the CLI β€” caller
// passes the full thing so this script doesn't need to guess shebangs:
@@ -79,18 +82,23 @@ const cmdStop = findHook('Stop', undefined);
let failed = 0;
const cases = [];
-const run = (name, cmd, stdin, assertions) => {
+const run = (name, cmd, stdin, assertions, options = {}) => {
+ const env = {
+ ...process.env,
+ CLAUDE_PLUGIN_ROOT: PLUGIN_ROOT,
+ RUFLO_HOOK_CLI_OVERRIDE: options.cliOverride ?? cliInvoke,
+ RUFLO_HOOK_SKIP_NPX: '1',
+ ...options.env,
+ };
+ for (const key of options.unsetEnv ?? []) delete env[key];
+ if (options.debug !== false) env.RUFLO_HOOK_DEBUG_STDOUT = '1';
+ else delete env.RUFLO_HOOK_DEBUG_STDOUT;
+
const r = spawnSync(cmd, {
shell: true,
input: stdin,
encoding: 'utf8',
- env: {
- ...process.env,
- CLAUDE_PLUGIN_ROOT: PLUGIN_ROOT,
- RUFLO_HOOK_CLI_OVERRIDE: cliInvoke,
- RUFLO_HOOK_SKIP_NPX: '1',
- RUFLO_HOOK_DEBUG_STDOUT: '1',
- },
+ env,
// A clean CI runner may spend more than 15 seconds starting the CLI and
// policy/memory backends for its first Edit hook. Keep a finite timeout,
// but allow that measured cold-start path to complete.
@@ -103,6 +111,9 @@ const run = (name, cmd, stdin, assertions) => {
for (const a of assertions) {
if (a.contains && !combined.includes(a.contains)) errors.push(`missing "${a.contains}" in output`);
if (a.absent && combined.includes(a.absent)) errors.push(`unexpected "${a.absent}" in output`);
+ if (Object.hasOwn(a, 'stdoutEquals') && (r.stdout ?? '') !== a.stdoutEquals) {
+ errors.push(`stdout was ${JSON.stringify(r.stdout ?? '')}, expected ${JSON.stringify(a.stdoutEquals)}`);
+ }
}
if (errors.length === 0) {
console.log(`ok: ${name}`);
@@ -119,25 +130,62 @@ const run = (name, cmd, stdin, assertions) => {
};
// --- PreToolUse: modify-bash / modify-file ---
-run('PreToolUse (Bash) always emits permission-allow JSON',
+const cursorEnv = { unsetEnv: ['PLUGIN_ROOT', 'PLUGIN_DATA'] };
+const codexEnv = {
+ env: {
+ PLUGIN_ROOT,
+ PLUGIN_DATA: join(PLUGIN_ROOT, '.test-data'),
+ },
+ cliOverride: `${process.execPath} ${HOOK_RECORDER}`,
+};
+
+run('Cursor PreToolUse (Bash) emits permission-allow JSON',
cmdModifyBash,
'{"tool_input":{"command":"echo hi"}}',
- [{ contains: '{"permission":"allow"}' }]);
+ [{ contains: '{"permission":"allow"}' }],
+ cursorEnv);
-run('PreToolUse (Edit) always emits permission-allow JSON',
+run('Cursor PreToolUse (Edit) emits permission-allow JSON',
cmdModifyFile,
'{"tool_input":{"file_path":"/tmp/foo.ts"}}',
- [{ contains: '{"permission":"allow"}' }]);
+ [{ contains: '{"permission":"allow"}' }],
+ cursorEnv);
-run('PreToolUse (Bash) emits permission-allow even with empty stdin',
+run('Cursor PreToolUse (Bash) emits permission-allow even with empty stdin',
cmdModifyBash,
'',
- [{ contains: '{"permission":"allow"}' }]);
+ [{ contains: '{"permission":"allow"}' }],
+ cursorEnv);
-run('PreToolUse (Bash) emits permission-allow even with malformed JSON',
+run('Cursor PreToolUse (Bash) emits permission-allow even with malformed JSON',
cmdModifyBash,
'{not json',
- [{ contains: '{"permission":"allow"}' }]);
+ [{ contains: '{"permission":"allow"}' }],
+ cursorEnv);
+
+run('Codex PreToolUse (Bash) exits 0 with empty stdout',
+ cmdModifyBash,
+ '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"}}',
+ [{ stdoutEquals: '' }],
+ { ...codexEnv, debug: false });
+
+run('Codex PreToolUse (Edit) exits 0 with empty stdout',
+ cmdModifyFile,
+ '{"hook_event_name":"PreToolUse","tool_name":"apply_patch","tool_input":{"command":"*** Begin Patch"}}',
+ [{ stdoutEquals: '' }],
+ { ...codexEnv, debug: false });
+
+run('Codex PreToolUse (Bash) still invokes telemetry',
+ cmdModifyBash,
+ '{"hook_event_name":"PreToolUse","tool_name":"Bash","tool_input":{"command":"echo hi"}}',
+ [{ contains: 'hook-telemetry:modify-bash' }, { absent: '{"permission":"allow"}' }],
+ codexEnv);
+
+run('Codex PreToolUse (Edit) still invokes telemetry',
+ cmdModifyFile,
+ '{"hook_event_name":"PreToolUse","tool_name":"apply_patch","tool_input":{"command":"*** Begin Patch"}}',
+ [{ contains: 'hook-telemetry:modify-file' }, { absent: '{"permission":"allow"}' }],
+ codexEnv);
// --- PostToolUse: post-edit ---
run('Edit hook records file_path (regression #1859: was "true")',
@@ -208,5 +256,37 @@ run('Stop hook runs session-end without error',
'{}',
[{ absent: 'Required option missing' }, { absent: 'Invalid value' }]);
+// #2640 β€” project settings + marketplace plugin can dispatch the same event.
+// The shared atomic claim makes the second side-effecting invocation a no-op.
+{
+ const dedupDir = mkdtempSync(join(tmpdir(), 'ruflo-hook-dedup-test-'));
+ const payload = '{"tool_use_id":"toolu_dedup_2640","tool_input":{"file_path":"/tmp/dedup.ts"}}';
+ const env = {
+ ...process.env,
+ CLAUDE_PLUGIN_ROOT: PLUGIN_ROOT,
+ CLAUDE_PROJECT_DIR: PLUGIN_ROOT,
+ RUFLO_HOOK_CLI_OVERRIDE: `${process.execPath} ${HOOK_RECORDER}`,
+ RUFLO_HOOK_DEBUG_STDOUT: '1',
+ RUFLO_HOOK_SKIP_NPX: '1',
+ RUFLO_HOOK_DEDUP_DIR: dedupDir,
+ };
+ try {
+ const first = spawnSync(cmdPostEdit, { shell: true, input: payload, encoding: 'utf8', env });
+ const second = spawnSync(cmdPostEdit, { shell: true, input: payload, encoding: 'utf8', env });
+ const ok = first.status === 0 && second.status === 0 &&
+ (first.stdout || '').includes('hook-telemetry:post-edit') &&
+ !(second.stdout || '').includes('hook-telemetry:post-edit');
+ if (ok) {
+ console.log('ok: duplicate post-edit event executes side effects exactly once');
+ } else {
+ console.error('FAIL: duplicate post-edit event was not deduplicated');
+ failed++;
+ }
+ cases.push('duplicate post-edit event executes side effects exactly once');
+ } finally {
+ rmSync(dedupDir, { recursive: true, force: true });
+ }
+}
+
console.log(`\n${cases.length - failed}/${cases.length} passed`);
process.exit(failed === 0 ? 0 : 1);
diff --git a/plugins/ruflo-core/scripts/witness/verify.mjs b/plugins/ruflo-core/scripts/witness/verify.mjs
index 6df97af425..e0df1a51e2 100644
--- a/plugins/ruflo-core/scripts/witness/verify.mjs
+++ b/plugins/ruflo-core/scripts/witness/verify.mjs
@@ -5,23 +5,26 @@
* Project-agnostic β€” works without ruflo CLI being installed.
*
* Usage:
- * node verify.mjs --manifest <path> [--root <path>] [--json]
+ * node verify.mjs --manifest <path> [--root <path>] [--source-only] [--json]
*
* Exit codes:
* 0 β€” signature valid + all fixes pass or drift (marker present)
* 1 β€” signature invalid OR any fix regressed/missing (real failure)
* 2 β€” bad arguments / file not found OR precondition not met
- * (e.g. @noble/ed25519 not installed, or dist files not built β€”
- * source-only checkout without `npm ci && npm run build`).
+ * (e.g. dist files not built during full-tree verification).
* Issue #1880: scheduled runners use this to distinguish a
* "needs install+build" environment from a real verification
* failure, so we stop filing recurring issues on every cron run.
*/
import { readFileSync, existsSync } from 'node:fs';
-import { resolve, join, sep } from 'node:path';
-import { createHash } from 'node:crypto';
-import { createRequire } from 'node:module';
+import { resolve, join } from 'node:path';
+import {
+ createHash,
+ createPrivateKey,
+ createPublicKey,
+ verify as verifyEd25519,
+} from 'node:crypto';
import { fileSha256, fileContains } from './lib.mjs';
const args = parseArgs(process.argv.slice(2));
@@ -32,28 +35,33 @@ if (!existsSync(manifestPath)) { console.error(`not found: ${manifestPath}`); pr
const repoRoot = resolve(args.root ?? process.cwd());
const asJson = !!args.json;
+const sourceOnly = !!args['source-only'];
const witness = JSON.parse(readFileSync(manifestPath, 'utf8'));
// ─── signature ────────────────────────────────────────────────────
-const sig = await verifySignature(witness, repoRoot);
+const sig = verifySignature(witness);
-// Issue #1880 β€” if @noble/ed25519 isn't installed, this is a
-// precondition failure, not a verification failure. Exit 2 so the
-// scheduled runner can distinguish "install needed" from a real
-// regression and stop filing duplicate issues every 12 hours.
-if (sig.reason === 'noble-ed25519-not-installed') {
- if (asJson) {
- console.log(JSON.stringify(
- { ok: false, precondition: 'noble-ed25519-not-installed', signature: sig },
- null, 2
- ));
- }
+// ─── per-fix marker check ─────────────────────────────────────────
+const allFixes = witness.manifest.fixes;
+const selectedFixes = sourceOnly
+ ? allFixes.filter((fix) => !isGeneratedDistPath(fix.file))
+ : allFixes;
+const skippedGenerated = allFixes.length - selectedFixes.length;
+
+if (sourceOnly && selectedFixes.length === 0) {
+ const result = {
+ ok: false,
+ scope: 'source-only',
+ precondition: 'no-source-entries',
+ signature: sig,
+ };
+ if (asJson) console.log(JSON.stringify(result, null, 2));
+ else console.error('verify.mjs: manifest contains no source entries to verify');
process.exit(2);
}
-// ─── per-fix marker check ─────────────────────────────────────────
-const fileResults = witness.manifest.fixes.map((fix) => {
+const fileResults = selectedFixes.map((fix) => {
const installed = join(repoRoot, fix.file);
if (!existsSync(installed)) {
return { ...fix, status: 'missing', sha256Match: false, markerPresent: false };
@@ -71,6 +79,7 @@ const summary = {
drift: fileResults.filter(r => r.status === 'drift').length,
regressed: fileResults.filter(r => r.status === 'regressed').length,
missing: fileResults.filter(r => r.status === 'missing').length,
+ skippedGenerated,
};
// Issue #1880 / #2528 β€” heuristic: if the only missing entries are
@@ -83,16 +92,12 @@ const allMissing = fileResults.length > 0
&& summary.missing === fileResults.length;
const missingResults = fileResults.filter(r => r.status === 'missing');
const missingOnlyDist = missingResults.length > 0
- && missingResults.every(r => r.file && (
- r.file.includes(`${sep}dist${sep}`) || r.file.includes('/dist/')
- ));
-const referencesDist = fileResults.some(r => r.file && (
- r.file.includes(`${sep}dist${sep}`) || r.file.includes('/dist/')
-));
-if ((allMissing && referencesDist) || (missingOnlyDist && summary.regressed === 0)) {
+ && missingResults.every(r => isGeneratedDistPath(r.file));
+const referencesDist = fileResults.some(r => isGeneratedDistPath(r.file));
+if (!sourceOnly && ((allMissing && referencesDist) || (missingOnlyDist && summary.regressed === 0))) {
if (asJson) {
console.log(JSON.stringify(
- { ok: false, precondition: 'dist-not-built', signature: sig, summary },
+ { ok: false, scope: 'full', precondition: 'dist-not-built', signature: sig, summary },
null, 2
));
} else {
@@ -112,14 +117,19 @@ const ok = sig.signatureValid && sig.manifestHashOk && sig.publicKeyReproducible
&& summary.regressed === 0 && summary.missing === 0;
if (asJson) {
- console.log(JSON.stringify({ ok, signature: sig, summary, results: fileResults }, null, 2));
+ console.log(JSON.stringify(
+ { ok, scope: sourceOnly ? 'source-only' : 'full', signature: sig, summary, results: fileResults },
+ null,
+ 2
+ ));
} else {
+ console.log(`Verification scope: ${sourceOnly ? 'source-only' : 'full'}`);
console.log('Manifest signature:');
console.log(` hash matches: ${sig.manifestHashOk ? 'yes' : 'NO'}`);
console.log(` public key reproducible: ${sig.publicKeyReproducible ? 'yes' : 'NO'}`);
console.log(` Ed25519 signature valid: ${sig.signatureValid ? 'yes' : 'NO'}`);
console.log('');
- console.log(`Summary: pass=${summary.pass} drift=${summary.drift} regressed=${summary.regressed} missing=${summary.missing}`);
+ console.log(`Summary: pass=${summary.pass} drift=${summary.drift} regressed=${summary.regressed} missing=${summary.missing} skipped-generated=${summary.skippedGenerated}`);
if (summary.regressed > 0) {
console.log('\nRegressed:');
for (const r of fileResults.filter(r => r.status === 'regressed')) {
@@ -137,71 +147,60 @@ if (asJson) {
process.exit(ok ? 0 : 1);
// ─── ed25519 helpers ─────────────────────────────────────────────
-async function verifySignature(witness, repoRoot) {
- // Probe multiple plausible install roots β€” pnpm's isolated linker
- // doesn't hoist transitive deps to v3/node_modules, so we also check
- // workspace packages that declare @noble/ed25519 directly. A user's
- // flat npm install satisfies the first probe; pnpm satisfies the latter.
- let ed;
- let probeErr;
- const probes = [
- repoRoot,
- join(repoRoot, 'v3'),
- join(repoRoot, 'v3/@claude-flow/cli'),
- join(repoRoot, 'v3/@claude-flow/plugin-agent-federation'),
- ];
- for (const root of probes) {
- try { ed = createRequire(join(root, 'noop.js'))('@noble/ed25519'); break; }
- catch (e) { probeErr = e; }
- }
- if (!ed) {
- // ruflo#1880 β€” the scheduled 12h verification has bounced off this
- // 6+ times. Spell out the fix in the error message instead of
- // leaving the operator to chase it.
- console.error(
- `verify.mjs: could not load @noble/ed25519 from any of:\n` +
- ` ${probes.join('\n ')}\n` +
- ` last error: ${probeErr?.message ?? '?'}\n` +
- `\n` +
- `Fix: from the repo root, run \`npm install\` (the dep is declared\n` +
- `in the root package.json under @noble/ed25519). If your runner\n` +
- `is a source-only checkout, your verification pipeline must run\n` +
- `\`npm ci && npm run build\` before invoking this script. See #1880\n` +
- `for the full diagnosis.`
+function verifySignature(witness) {
+ try {
+ const recomputed = createHash('sha256').update(JSON.stringify(witness.manifest)).digest('hex');
+ const manifestHashOk = recomputed === witness.integrity.manifestHash;
+ const seed = createHash('sha256')
+ .update(witness.manifest.gitCommit + ':ruflo-witness/v1')
+ .digest();
+
+ // RFC 8410 DER wrappers let Node/OpenSSL derive and verify Ed25519 keys
+ // without a package install. The witness format remains byte-compatible
+ // with manifests produced by @noble/ed25519.
+ const privateKey = createPrivateKey({
+ key: Buffer.concat([
+ Buffer.from('302e020100300506032b657004220420', 'hex'),
+ seed,
+ ]),
+ format: 'der',
+ type: 'pkcs8',
+ });
+ const reproducedKey = createPublicKey(privateKey)
+ .export({ format: 'der', type: 'spki' })
+ .subarray(-32);
+ const publicKeyReproducible =
+ reproducedKey.toString('hex') === witness.integrity.publicKey;
+
+ const declaredKey = createPublicKey({
+ key: Buffer.concat([
+ Buffer.from('302a300506032b6570032100', 'hex'),
+ Buffer.from(witness.integrity.publicKey, 'hex'),
+ ]),
+ format: 'der',
+ type: 'spki',
+ });
+ const signatureValid = verifyEd25519(
+ null,
+ Buffer.from(witness.integrity.manifestHash, 'hex'),
+ declaredKey,
+ Buffer.from(witness.integrity.signature, 'hex'),
);
+ return { manifestHashOk, publicKeyReproducible, signatureValid, verifier: 'node:crypto' };
+ } catch (error) {
return {
manifestHashOk: false,
publicKeyReproducible: false,
signatureValid: false,
- // Machine-parseable hint for the scheduled runner so it can
- // distinguish "missing dep" from a real signature failure.
- reason: 'noble-ed25519-not-installed',
+ verifier: 'node:crypto',
+ reason: 'signature-verification-error',
+ error: error instanceof Error ? error.message : String(error),
};
}
+}
- // noble/ed25519 v2 freezes `etc` and ships sync verify by default β€” the
- // sha512Sync shim is only needed for v1. Guard the assignment so it works
- // on both major versions (#2274).
- if (!ed.etc.sha512Sync) {
- try {
- ed.etc.sha512Sync = (...m) => { const h = createHash('sha512'); for (const x of m) h.update(x); return h.digest(); };
- } catch {
- // v2 freezes `etc`; assignment is unnecessary because sha512Sync
- // is already wired internally. Swallow the TypeError and continue.
- }
- }
-
- const recomputed = createHash('sha256').update(JSON.stringify(witness.manifest)).digest('hex');
- const manifestHashOk = recomputed === witness.integrity.manifestHash;
- const seed = createHash('sha256').update(witness.manifest.gitCommit + ':ruflo-witness/v1').digest();
- const reKey = ed.getPublicKey(seed);
- const publicKeyReproducible = Buffer.from(reKey).toString('hex') === witness.integrity.publicKey;
- const signatureValid = ed.verify(
- Buffer.from(witness.integrity.signature, 'hex'),
- Buffer.from(witness.integrity.manifestHash, 'hex'),
- Buffer.from(witness.integrity.publicKey, 'hex'),
- );
- return { manifestHashOk, publicKeyReproducible, signatureValid };
+function isGeneratedDistPath(file) {
+ return typeof file === 'string' && file.split(/[\\/]/).includes('dist');
}
function parseArgs(argv) {
diff --git a/plugins/ruflo-core/skills/ruflo-status/SKILL.md b/plugins/ruflo-core/skills/ruflo-status/SKILL.md
new file mode 100644
index 0000000000..800e36d8cd
--- /dev/null
+++ b/plugins/ruflo-core/skills/ruflo-status/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: ruflo-status
+description: Diagnose Ruflo health, then report system, MCP server, and active-agent status without changing the installation
+argument-hint: "[--fix]"
+allowed-tools: Bash(npx *)
+---
+
+# Ruflo status
+
+Use this skill when the user asks for Ruflo health, diagnostics, MCP server
+state, or active-agent status.
+
+## Default read-only workflow
+
+Run these commands in order:
+
+```bash
+npx @claude-flow/cli@latest doctor
+npx @claude-flow/cli@latest status
+```
+
+Summarize the diagnostics and status together. Do not repair, reset, start,
+stop, install, or otherwise change anything during the default workflow.
+
+## Explicit repair workflow
+
+Only when the user explicitly asks to fix or auto-repair the installation,
+replace the first command with:
+
+```bash
+npx @claude-flow/cli@latest doctor --fix
+npx @claude-flow/cli@latest status
+```
+
+Report what the repair changed and the resulting status. Never infer
+authorization for `doctor --fix` from a request to check or diagnose Ruflo.
diff --git a/plugins/ruflo-core/skills/witness/SKILL.md b/plugins/ruflo-core/skills/witness/SKILL.md
index 16d231b2cc..90884b0ca3 100644
--- a/plugins/ruflo-core/skills/witness/SKILL.md
+++ b/plugins/ruflo-core/skills/witness/SKILL.md
@@ -35,7 +35,7 @@ node plugins/ruflo-core/scripts/witness/init.mjs --root .
# while the fix is present. If someone reverts the fix, the marker
# disappears and `verify` reports it as `regressed`.
-# Regenerate the manifest (signs with Ed25519 from current gitCommit)
+# Regenerate the manifest (signing requires @noble/ed25519)
npm i @noble/ed25519
node plugins/ruflo-core/scripts/witness/regen.mjs \
--manifest verification.md.json \
@@ -45,6 +45,11 @@ node plugins/ruflo-core/scripts/witness/regen.mjs \
# Verify markers are present in the live tree
node plugins/ruflo-core/scripts/witness/verify.mjs \
--manifest verification.md.json
+
+# Or authenticate the manifest and check source markers in a clean clone.
+# Generated dist/ entries are explicitly reported as skipped.
+node plugins/ruflo-core/scripts/witness/verify.mjs \
+ --manifest verification.md.json --source-only
```
## Temporal queries (ADR-103)
@@ -100,3 +105,4 @@ and before `publish`. Failure modes:
| `signatureValid: no` | manifest hand-edited; re-run regen |
| `regressed: > 0` | a documented fix lost its marker since issuance |
| `missing: > 0` | a cited dist file no longer exists; rebuild or remove the entry |
+| `scope: source-only` | signature + source markers checked; generated entries intentionally skipped |
diff --git a/plugins/ruflo-metaharness/scripts/_harness.mjs b/plugins/ruflo-metaharness/scripts/_harness.mjs
index 1f4abc86b2..0b1ade0c3d 100755
--- a/plugins/ruflo-metaharness/scripts/_harness.mjs
+++ b/plugins/ruflo-metaharness/scripts/_harness.mjs
@@ -279,6 +279,7 @@ export function rankSeverity(s) {
* harness mcp-scan β€” <path>
*
* [INFO] No MCP security issues found
+ * [LOW ] Padded severity labels are also emitted by newer releases
* Policy is default-deny with safe capability grants and an audit log.
*
* Result: INFO (1 finding, 0 high)
@@ -293,7 +294,10 @@ export function parseMcpScanText(stdout) {
const lines = (stdout || '').split('\n');
let current = null;
for (const line of lines) {
- const m = /^\s*\[([A-Z]+)\]\s+(.+?)\s*$/.exec(line);
+ // metaharness <=0.3.0 emitted `[LOW]`; newer releases pad labels to a
+ // fixed-width column (`[LOW ]`). Accept optional whitespace before the
+ // closing bracket so both installed versions remain compatible.
+ const m = /^\s*\[([A-Z]+)\s*\]\s+(.+?)\s*$/.exec(line);
if (m) {
if (current) findings.push(current);
current = { severity: m[1].toLowerCase(), message: m[2] };
diff --git a/plugins/ruflo-metaharness/scripts/_invoke.mjs b/plugins/ruflo-metaharness/scripts/_invoke.mjs
index 31304ab580..9fed9b8943 100644
--- a/plugins/ruflo-metaharness/scripts/_invoke.mjs
+++ b/plugins/ruflo-metaharness/scripts/_invoke.mjs
@@ -12,10 +12,9 @@
// - classifyDegraded() timeout vs not-available distinction, per-package
// reason prefix
// - injectJson() append --json unless caller opted out / present
-// - parseTrailingJson() LAST-{...}-block extraction (the _darwin variant;
-// the old _harness FIRST-block variant was a live
-// bug β€” a progress line containing `{...}` would
-// shadow the final structured result)
+// - parseTrailingJson() complete trailing-object extraction (progress
+// lines before the JSON are ignored, while nested
+// objects remain part of the root payload)
// - ensureCachedInstall() one-time `npm install --prefix ~/.ruflo/<name>-cache-<pin>`
// of a PINNED range β€” generalizes _redblue.mjs /
// gepa.mjs; the versioned dir means pin bumps
@@ -69,18 +68,18 @@ export function injectJson(args, wantJson) {
/**
* Parse the trailing JSON object from mixed stdout. CLIs in this family emit
- * human-readable progress first and a structured JSON object LAST β€” so grab
- * the last parseable {...} block, falling back to a greedy whole-span match
- * for nested objects the lazy regex fragments.
+ * human-readable progress first and a structured JSON object LAST.
+ *
+ * Trying candidate opening braces against the complete trailing substring is
+ * intentional. A regex that selects the "last parseable {...} block" returns
+ * the final nested finding from pretty-printed payloads instead of the root
+ * object, silently discarding findings[], worst, and other security fields.
*/
export function parseTrailingJson(stdout) {
- const s = stdout || '';
- const matches = [...s.matchAll(/\{[\s\S]*?\}/g)];
- for (let i = matches.length - 1; i >= 0; i--) {
- try { return JSON.parse(matches[i][0]); } catch { /* try previous */ }
+ const s = String(stdout || '').trimEnd();
+ for (let i = s.lastIndexOf('{'); i >= 0; i = s.lastIndexOf('{', i - 1)) {
+ try { return JSON.parse(s.slice(i)); } catch { /* try the enclosing object */ }
}
- const greedy = /\{[\s\S]*\}/.exec(s);
- if (greedy) { try { return JSON.parse(greedy[0]); } catch { return null; } }
return null;
}
diff --git a/plugins/ruflo-metaharness/scripts/mcp-scan.mjs b/plugins/ruflo-metaharness/scripts/mcp-scan.mjs
index 8ca1311f5a..a98aecbcde 100755
--- a/plugins/ruflo-metaharness/scripts/mcp-scan.mjs
+++ b/plugins/ruflo-metaharness/scripts/mcp-scan.mjs
@@ -40,18 +40,17 @@ function main() {
}
const r = runHarness(['mcp-scan', ARGS.path]);
if (r.degraded) { emitDegradedJsonAndExit(r.reason); return; }
- if (r.exitCode !== 0 && r.exitCode !== 1) {
- // exit 1 from harness can be "findings present"; only treat other
- // non-zero as a real failure.
+ if (!r.json && r.exitCode !== 0 && r.exitCode !== 1) {
+ // Non-zero verdict exits are valid when accompanied by structured JSON.
+ // Without a payload, exit codes other than the historical findings=1
+ // remain invocation failures.
console.error(`mcp-scan: harness exited ${r.exitCode}`);
if (r.stderr) console.error(r.stderr.slice(0, 400));
process.exit(2);
}
- // The JSON output shape from `harness mcp-scan` historically didn't
- // include structured findings β€” it emits text even with --json. Parse
- // the text into findings (iter 50) so audit-trend's introduced/cleared
- // diff actually works. If a future upstream version DOES emit
- // findings[], the parsed-text findings are overridden.
+ // Older `harness mcp-scan` releases emitted text even with --json. Keep
+ // the text parser as a backwards-compatible fallback, but prefer current
+ // structured findings when the upstream command supplies them.
const parsed = parseMcpScanText(r.stdout);
// iter 124 β€” normalize finding shape so consumers see a stable contract.
// Upstream [email protected] JSON path emits {id, severity, title, detail};
diff --git a/plugins/ruflo-metaharness/scripts/smoke.sh b/plugins/ruflo-metaharness/scripts/smoke.sh
index 981d716c23..48d0c5a121 100755
--- a/plugins/ruflo-metaharness/scripts/smoke.sh
+++ b/plugins/ruflo-metaharness/scripts/smoke.sh
@@ -253,6 +253,47 @@ grep -q "bin.harness" "$F" 2>/dev/null || miss="$miss no-harness-bin"
grep -q "cwd: opts" "$F" || miss="$miss no-cwd-passthrough"
[[ -z "$miss" ]] && ok || bad "$miss"
+step "17z80. HIGH security findings survive wrapper + composite boundaries (#2750)"
+miss=""
+SEC_FIXTURE=$(mktemp -d)
+mkdir -p "$SEC_FIXTURE/.harness" "$SEC_FIXTURE/.claude"
+printf '%s\n' '{"defaultDeny":false,"allowShell":true,"allowNetwork":true}' \
+ > "$SEC_FIXTURE/.harness/mcp-policy.json"
+printf '%s\n' '{"permissions":{"allow":["mcp__*"],"deny":[]},"mcpServers":{"x":{"command":"bash"}}}' \
+ > "$SEC_FIXTURE/.claude/settings.json"
+
+THREAT_OUT=$(node "$ROOT/scripts/threat-model.mjs" --path "$SEC_FIXTURE" --fail-on high --format json 2>/dev/null)
+THREAT_EXIT=$?
+SCAN_OUT=$(node "$ROOT/scripts/mcp-scan.mjs" --path "$SEC_FIXTURE" --fail-on high --format json 2>/dev/null)
+SCAN_EXIT=$?
+OIA_OUT=$(node "$ROOT/scripts/oia-audit.mjs" --path "$SEC_FIXTURE" --dry-run --format json 2>/dev/null)
+OIA_EXIT=$?
+
+[[ "$THREAT_EXIT" -eq 1 ]] || miss="$miss threat-exit-${THREAT_EXIT}"
+[[ "$SCAN_EXIT" -eq 1 ]] || miss="$miss scan-exit-${SCAN_EXIT}"
+[[ "$OIA_EXIT" -eq 0 ]] || miss="$miss oia-exit-${OIA_EXIT}"
+printf '%s' "$THREAT_OUT" | node -e '
+ let s=""; process.stdin.on("data",d=>s+=d); process.stdin.on("end",()=>{
+ try { const x=JSON.parse(s); if(x.worst!=="high" || !x.alert?.triggered || x.findings?.length<1) process.exitCode=1; }
+ catch { process.exitCode=1; }
+ });
+' || miss="$miss threat-lost-high"
+printf '%s' "$SCAN_OUT" | node -e '
+ let s=""; process.stdin.on("data",d=>s+=d); process.stdin.on("end",()=>{
+ try { const x=JSON.parse(s); if(x.worst!=="high" || !x.alert?.triggered || x.findings?.length<1) process.exitCode=1; }
+ catch { process.exitCode=1; }
+ });
+' || miss="$miss scan-lost-high"
+printf '%s' "$OIA_OUT" | node -e '
+ let s=""; process.stdin.on("data",d=>s+=d); process.stdin.on("end",()=>{
+ try { const x=JSON.parse(s); if(x.composite?.worst!=="high" || x.components?.mcpScan?.json?.findings?.length<1) process.exitCode=1; }
+ catch { process.exitCode=1; }
+ });
+' || miss="$miss oia-lost-high"
+rm -f "$SEC_FIXTURE/.harness/mcp-policy.json" "$SEC_FIXTURE/.claude/settings.json"
+rmdir "$SEC_FIXTURE/.harness" "$SEC_FIXTURE/.claude" "$SEC_FIXTURE"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
step "17z79. oia-audit-weekly.yml retains iter-108 hard-fail + iter-109 dispatch inputs (iter 116)"
miss=""
# Two load-bearing invariants accumulated in the weekly cron:
@@ -1398,9 +1439,24 @@ done
grep -q "export function rankSeverity\|return SEVERITY_RANK\[.*\] ?? 0" "$HARNESS" 2>/dev/null || miss="$miss no-safe-rank-lookup"
# Rationale documented at the new location
grep -q "NaN-compare hazard" "$HARNESS" 2>/dev/null || miss="$miss no-rationale-comment"
-# Runtime: live oia-audit still produces clean (only INFO finding)
+# Runtime: the live audit produces a recognized severity. Repository contents
+# legitimately change the result (for example, current upstream reports LOW
+# for unpinned ranges), so "clean" is not a stable compatibility invariant.
OUT=$(node "$OIA" --dry-run --format json 2>/dev/null)
-echo "$OUT" | grep -q '"worst": "clean"' || miss="$miss live-not-clean"
+printf '%s' "$OUT" | node -e '
+ let input = "";
+ process.stdin.on("data", chunk => { input += chunk; });
+ process.stdin.on("end", () => {
+ try {
+ const payload = JSON.parse(input);
+ if (payload.degraded === true) return;
+ const known = new Set(["clean", "info", "low", "medium", "warn", "high", "error", "critical"]);
+ if (!known.has(payload.composite?.worst)) process.exitCode = 1;
+ } catch {
+ process.exitCode = 1;
+ }
+ });
+' || miss="$miss live-invalid-worst"
[[ -z "$miss" ]] && ok || bad "$miss"
step "17z24. doctor required-files include iter-53 + iter-56 surfaces (iter 61)"
diff --git a/plugins/ruflo-metaharness/scripts/test-similarity.mjs b/plugins/ruflo-metaharness/scripts/test-similarity.mjs
index 45ec59cd01..4b0ae17029 100755
--- a/plugins/ruflo-metaharness/scripts/test-similarity.mjs
+++ b/plugins/ruflo-metaharness/scripts/test-similarity.mjs
@@ -26,6 +26,7 @@ import {
} from './_similarity.mjs';
// iter 64 β€” also test the iter-63 shared severity primitives
import { SEVERITY_RANK, rankSeverity, parseMcpScanText } from './_harness.mjs';
+import { parseTrailingJson } from './_invoke.mjs';
const ARGS = (() => {
const a = { format: 'table' };
@@ -273,6 +274,22 @@ assert(single.summary?.overallSeverity === 'info',
assert(single.summary?.totalCount === 1,
'summary.totalCount === 1 from "(1 finding,"');
+// Newer metaharness releases align severity labels to a fixed-width column.
+// Keep parsing the legacy compact form above while accepting `[LOW ]`.
+const padded = parseMcpScanText(`harness mcp-scan β€” /repo
+
+ [LOW ] 8 unpinned dependency range(s)
+ Floating ranges weaken supply-chain reproducibility.
+
+Result: LOW (1 finding, 0 high)
+`);
+assert(padded.findings.length === 1, 'padded [LOW ] block β†’ 1 finding');
+assert(padded.findings[0].severity === 'low',
+ 'padded severity lowercased without trailing whitespace');
+assert(padded.findings[0].message.includes('8 unpinned dependency range(s)') &&
+ padded.findings[0].message.includes('supply-chain reproducibility'),
+ 'padded finding message and continuation extracted');
+
// Continuation line β€” indented text appends to previous finding
const cont = parseMcpScanText(`
[HIGH] Exposed credential path
@@ -314,6 +331,27 @@ assert(mixed.findings.length === 1,
assert(mixed.findings[0].severity === 'high',
'strict regex captured the uppercase entry');
+console.log('\nPhase 11 β€” complete trailing JSON extraction');
+
+const nestedJson = parseTrailingJson(`progress: scanning {not-json}
+{
+ "dir": "/repo",
+ "findings": [
+ { "id": "allow-shell", "severity": "high" },
+ { "id": "no-audit-log", "severity": "medium" }
+ ],
+ "worst": "high"
+}
+`);
+assert(nestedJson?.dir === '/repo', 'mixed stdout returns root JSON object');
+assert(nestedJson?.findings?.length === 2,
+ 'nested findings remain attached to root payload');
+assert(nestedJson?.findings?.[1]?.id === 'no-audit-log',
+ 'extractor does not return the last nested object');
+assert(nestedJson?.worst === 'high', 'root-level severity is preserved');
+assert(parseTrailingJson('progress only {not-json}') === null,
+ 'non-JSON progress braces return null');
+
// ──────────────────────────────────────────────────────────────────
const summary = {
passed, failed,
diff --git a/plugins/ruflo-metaharness/scripts/threat-model.mjs b/plugins/ruflo-metaharness/scripts/threat-model.mjs
index 988bdfcbfd..b3c2566eda 100755
--- a/plugins/ruflo-metaharness/scripts/threat-model.mjs
+++ b/plugins/ruflo-metaharness/scripts/threat-model.mjs
@@ -26,7 +26,10 @@ function main() {
}
const r = runHarness(['threat-model', ARGS.path]);
if (r.degraded) { emitDegradedJsonAndExit(r.reason); return; }
- if (r.exitCode !== 0 && r.exitCode !== 1) {
+ // Upstream uses exit 2 for a valid HIGH verdict. A parsed JSON payload is
+ // authoritative regardless of that domain exit code; only reject a
+ // non-zero invocation when it produced no structured result.
+ if (!r.json && r.exitCode !== 0 && r.exitCode !== 1) {
console.error(`threat-model: harness exited ${r.exitCode}`);
if (r.stderr) console.error(r.stderr.slice(0, 400));
process.exit(2);
diff --git a/ruflo/package.json b/ruflo/package.json
index 4ed8dbf84f..33767dcf2c 100644
--- a/ruflo/package.json
+++ b/ruflo/package.json
@@ -1,6 +1,6 @@
{
"name": "ruflo",
- "version": "3.32.35",
+ "version": "3.32.36",
"description": "Ruflo - Enterprise AI agent orchestration platform. Deploy 60+ specialized agents in coordinated swarms with self-learning, fault-tolerant consensus, vector memory, and MCP integration",
"main": "bin/ruflo.js",
"type": "module",
@@ -40,7 +40,7 @@
"package:rvf": "bash src/scripts/package-rvf.sh"
},
"dependencies": {
- "@claude-flow/cli": "^3.32.35"
+ "@claude-flow/cli": "^3.32.36"
},
"optionalDependencies": {},
"overrides": {
diff --git a/ruflo/src/mcp-bridge/Dockerfile b/ruflo/src/mcp-bridge/Dockerfile
index b29a148d16..77210dc73b 100644
--- a/ruflo/src/mcp-bridge/Dockerfile
+++ b/ruflo/src/mcp-bridge/Dockerfile
@@ -1,4 +1,6 @@
-FROM node:20-slim
+# Node 24 is Active LTS through April 2028. Keep this pinned to a
+# supported LTS line; test-security-lock.js fails if it drifts to EOL.
+FROM node:24-slim
WORKDIR /app
diff --git a/ruflo/src/mcp-bridge/test-security-lock.js b/ruflo/src/mcp-bridge/test-security-lock.js
index 9b5b665eee..383469c35f 100755
--- a/ruflo/src/mcp-bridge/test-security-lock.js
+++ b/ruflo/src/mcp-bridge/test-security-lock.js
@@ -11,6 +11,7 @@
* 4. `requireAuth` uses `timingSafeEqual` (constant-time compare)
* 5. `executeTool` denies terminal_execute unless `MCP_ENABLE_TERMINAL === "true"` (Phase 1d + 2a)
* 6. CORS respects `MCP_CORS_ORIGIN` allowlist (Phase 3b)
+ * 9. Both production images use the supported Node 24 LTS line (#2847)
*
* Runs offline (no server, no deps). CI-safe.
*
@@ -26,6 +27,10 @@ const BRIDGES = [
path.join(HERE, "index.js"), // ruflo/src/mcp-bridge/index.js
path.join(HERE, "..", "ruvocal", "mcp-bridge", "index.js"), // ruvocal variant (deployed)
];
+const DOCKERFILES = [
+ path.join(HERE, "Dockerfile"),
+ path.join(HERE, "..", "ruvocal", "mcp-bridge", "Dockerfile"),
+];
const CHECKS = [
{
@@ -91,6 +96,24 @@ for (const bridge of BRIDGES) {
}
}
+for (const dockerfile of DOCKERFILES) {
+ if (!fs.existsSync(dockerfile)) {
+ console.error(`FAIL: Dockerfile missing: ${dockerfile}`);
+ hardFail = true;
+ continue;
+ }
+ const source = fs.readFileSync(dockerfile, "utf-8");
+ const rel = path.relative(path.join(HERE, "..", ".."), dockerfile);
+ console.log(`\n# ${rel}`);
+ if (/^FROM\s+node:24(?:[.-][^\s]+)?\s*$/m.test(source)) {
+ console.log(" βœ“ 9. supported-node-lts-runtime (#2847)");
+ } else {
+ console.log(" βœ— 9. supported-node-lts-runtime (#2847)");
+ console.log(" hint: production images must use the supported node:24 LTS line");
+ hardFail = true;
+ }
+}
+
if (hardFail) {
console.error("\nADR-166 security lock FAILED β€” a load-bearing control was removed or drifted.");
process.exit(1);
diff --git a/ruflo/src/ruvocal/mcp-bridge/Dockerfile b/ruflo/src/ruvocal/mcp-bridge/Dockerfile
index b29a148d16..77210dc73b 100644
--- a/ruflo/src/ruvocal/mcp-bridge/Dockerfile
+++ b/ruflo/src/ruvocal/mcp-bridge/Dockerfile
@@ -1,4 +1,6 @@
-FROM node:20-slim
+# Node 24 is Active LTS through April 2028. Keep this pinned to a
+# supported LTS line; test-security-lock.js fails if it drifts to EOL.
+FROM node:24-slim
WORKDIR /app
diff --git a/scripts/check-mcp-scan-format.mjs b/scripts/check-mcp-scan-format.mjs
index 94bf5d9d75..7926fe0bd1 100755
--- a/scripts/check-mcp-scan-format.mjs
+++ b/scripts/check-mcp-scan-format.mjs
@@ -6,8 +6,9 @@
// structured findings from its plain-text output. That parser depends
// on TWO format invariants:
//
-// 1. Finding lines: ` [SEV] <message>` (2-space indent, uppercase
-// severity inside brackets, message on same line)
+// 1. Finding lines: ` [SEV] <message>` or ` [SEV ] <message>`
+// (uppercase severity inside brackets, optional alignment padding,
+// message on same line)
//
// 2. Summary line: `Result: <SEV> (N finding, M high)`
//
@@ -81,14 +82,14 @@ async function main() {
const stdout = r.stdout || '';
const results = [];
- // 3. INVARIANT 1: at least one finding line in the expected shape
- // ` [SEV] <message>` where SEV is uppercase letters in brackets.
+ // 3. INVARIANT 1: at least one finding line in a supported shape:
+ // legacy `[SEV] <message>` or fixed-width `[SEV ] <message>`.
// Pre-iter-50 we never asserted this β€” upstream changing to
// `* SEV: message` would have been undetectable.
- const findingLineRegex = /^\s*\[([A-Z]+)\]\s+\S/m;
+ const findingLineRegex = /^\s*\[([A-Z]+)\s*\]\s+\S/m;
const findingMatch = findingLineRegex.exec(stdout);
results.push({
- check: 'finding line matches `[SEV] message` regex',
+ check: 'finding line matches `[SEV]` or padded `[SEV ]` message regex',
ok: findingMatch !== null,
detail: findingMatch ? `first match: [${findingMatch[1]}]` : 'no match β€” parser will return empty findings',
});
diff --git a/scripts/smoke-helper-signing-security.mjs b/scripts/smoke-helper-signing-security.mjs
new file mode 100644
index 0000000000..1e9bc97731
--- /dev/null
+++ b/scripts/smoke-helper-signing-security.mjs
@@ -0,0 +1,108 @@
+#!/usr/bin/env node
+/**
+ * Offline regression guard for helper-signing issues #2674 and #2675.
+ */
+import { spawnSync } from 'node:child_process';
+import { generateKeyPairSync, verify } from 'node:crypto';
+import {
+ cpSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
+import { tmpdir } from 'node:os';
+import { dirname, join, resolve } from 'node:path';
+
+const root = process.cwd();
+const cli = resolve(root, 'v3/@claude-flow/cli');
+const signer = join(cli, 'scripts/sign-helpers.mjs');
+const verifier = join(cli, 'scripts/verify-helpers.mjs');
+const failures = [];
+
+function check(name, condition, detail = '') {
+ console.log(` ${condition ? 'PASS' : 'FAIL'} ${name}`);
+ if (!condition) {
+ if (detail) console.log(` ${detail}`);
+ failures.push(name);
+ }
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'helper-signing-security-'));
+try {
+ const fixture = join(tmp, 'cli');
+ mkdirSync(join(fixture, 'scripts'), { recursive: true });
+ mkdirSync(join(fixture, '.claude', 'helpers'), { recursive: true });
+ cpSync(signer, join(fixture, 'scripts', 'sign-helpers.mjs'));
+ for (const name of ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs']) {
+ cpSync(join(cli, '.claude', 'helpers', name), join(fixture, '.claude', 'helpers', name));
+ }
+ writeFileSync(join(fixture, 'package.json'), JSON.stringify({ version: '0.0.0-security-test' }));
+
+ const { privateKey, publicKey } = generateKeyPairSync('ed25519');
+ const privatePem = privateKey.export({ format: 'pem', type: 'pkcs8' }).toString();
+ const result = spawnSync(
+ process.execPath,
+ [join(fixture, 'scripts', 'sign-helpers.mjs'), '--stdin-key'],
+ { input: privatePem, encoding: 'utf8', env: { ...process.env } },
+ );
+
+ check('stdin-only signing succeeds', result.status === 0, result.stderr);
+ check(
+ 'private key never reaches signer output',
+ !/BEGIN PRIVATE KEY|PRIVATE KEY-----/.test(result.stdout + result.stderr)
+ && !(result.stdout + result.stderr).includes(privatePem.slice(30, 70)),
+ (result.stdout + result.stderr).slice(0, 300),
+ );
+
+ const signed = JSON.parse(readFileSync(
+ join(fixture, '.claude', 'helpers', 'helpers.manifest.json'),
+ 'utf8',
+ ));
+ const sortedFiles = {};
+ for (const key of Object.keys(signed.manifest.files).sort()) sortedFiles[key] = signed.manifest.files[key];
+ const canonical = Buffer.from(JSON.stringify({
+ version: signed.manifest.version,
+ files: sortedFiles,
+ }));
+ check(
+ 'stdin key produced a valid Ed25519 signature',
+ verify(null, canonical, publicKey, Buffer.from(signed.signature, 'base64')),
+ );
+
+ const invalid = '-----BEGIN PRIVATE KEY-----\nnot-a-key\n-----END PRIVATE KEY-----\n';
+ const rejected = spawnSync(
+ process.execPath,
+ [join(fixture, 'scripts', 'sign-helpers.mjs'), '--stdin-key'],
+ { input: invalid, encoding: 'utf8' },
+ );
+ check(
+ 'invalid key fails with a redacted diagnostic',
+ rejected.status === 1
+ && /not a valid Ed25519 private key/.test(rejected.stderr)
+ && !rejected.stderr.includes('not-a-key'),
+ rejected.stderr,
+ );
+
+ const signerSource = readFileSync(signer, 'utf8');
+ check(
+ 'Windows uses the executable gcloud.cmd shim',
+ /process\.platform === 'win32'\s*\?\s*'gcloud\.cmd'\s*:\s*'gcloud'/.test(signerSource),
+ );
+
+ const verifierSource = readFileSync(verifier, 'utf8');
+ check(
+ 'runtime helper-signing module is the sole public-key source',
+ !verifierSource.includes('BEGIN PUBLIC KEY')
+ && verifierSource.includes("import('../dist/src/init/helper-signing.js')"),
+ );
+} finally {
+ rmSync(tmp, { recursive: true, force: true });
+}
+
+if (failures.length > 0) {
+ console.error(`smoke-helper-signing-security: ${failures.length} failure(s)`);
+ process.exit(1);
+}
+console.log('smoke-helper-signing-security: all checks passed');
diff --git a/scripts/smoke-witness-verify-precondition.mjs b/scripts/smoke-witness-verify-precondition.mjs
index 6c66cdd6de..bb2a208e3e 100644
--- a/scripts/smoke-witness-verify-precondition.mjs
+++ b/scripts/smoke-witness-verify-precondition.mjs
@@ -1,125 +1,70 @@
#!/usr/bin/env node
/**
- * Regression guard for ruvnet/ruflo#1880.
+ * Regression guard for source-only witness verification (#2729).
*
- * The 12-hour scheduled witness verification runs `verify.mjs` in a
- * source-only checkout (no `npm ci`, no `npm run build`) and conflates
- * two completely different failure modes:
- *
- * 1. `@noble/ed25519` not installed β†’ precondition (install needed)
- * 2. dist files referenced by manifest β†’ precondition (build needed)
- * not present on disk
- * 3. signature actually doesn't verify β†’ real failure
- * 4. specific dist file regressed β†’ real failure
- *
- * Before this guard, all four exited with code 1, so the scheduled
- * runner filed a duplicate "verification failed" issue every 12 hours
- * even though nothing was actually wrong with the manifest.
- *
- * verify.mjs now reserves exit 2 for preconditions (cases 1 and 2) and
- * keeps exit 1 strictly for real failures (cases 3 and 4). This smoke
- * drives both shapes through the script and asserts the contract holds.
- *
- * Fails CI if any of:
- * - missing @noble/ed25519 exit code is anything other than 2
- * - all-files-missing manifest exit code is anything other than 2
- * - precondition output missing the operator-facing fix hint
- * - precondition output missing the machine-parseable `reason` / `precondition` field
+ * The standalone verifier must:
+ * 1. cryptographically verify a signed manifest without node_modules;
+ * 2. validate every source marker while explicitly skipping generated dist/;
+ * 3. reject a tampered signature and a regressed source marker; and
+ * 4. retain exit 2 for legacy full-tree checks when dist has not been built.
*/
import { spawnSync } from 'node:child_process';
-import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync, rmSync } from 'node:fs';
+import {
+ cpSync,
+ existsSync,
+ mkdirSync,
+ mkdtempSync,
+ readFileSync,
+ rmSync,
+ writeFileSync,
+} from 'node:fs';
import { tmpdir } from 'node:os';
import { dirname, join, resolve } from 'node:path';
const REPO_ROOT = process.cwd();
const VERIFY = resolve(REPO_ROOT, 'plugins/ruflo-core/scripts/witness/verify.mjs');
const REAL_MANIFEST = resolve(REPO_ROOT, 'verification/macos/manifest.md.json');
-
-if (!existsSync(VERIFY)) {
- console.error(`smoke: not found: ${VERIFY}`);
- process.exit(1);
-}
-if (!existsSync(REAL_MANIFEST)) {
- console.error(`smoke: not found: ${REAL_MANIFEST}`);
- process.exit(1);
-}
-
const failures = [];
function record(name, condition, detail) {
- if (condition) {
- console.log(` PASS ${name}`);
- } else {
- console.log(` FAIL ${name}`);
+ console.log(` ${condition ? 'PASS' : 'FAIL'} ${name}`);
+ if (!condition) {
if (detail) console.log(` ${detail}`);
failures.push(name);
}
}
-// ── Case 1: @noble/ed25519 missing β†’ exit 2 (precondition) ──────────
-// Drop verify.mjs into an empty root with no node_modules anywhere up
-// the tree, so the ed25519 probe fails on every candidate.
-console.log('\nCase 1: @noble/ed25519 not installed (source-only)');
-{
- const tmp = mkdtempSync(join(tmpdir(), 'witness-smoke-nodep-'));
- // verify.mjs's probes use createRequire(join(root, 'noop.js')) which
- // walks up from `root`. Putting `root` deep under tmp ensures Node
- // walks /tmp/.../node_modules (absent) then /tmp/node_modules (absent)
- // then /node_modules (absent on CI) β€” no resolution.
- const isolatedRoot = join(tmp, 'isolated', 'repo');
- mkdirSync(isolatedRoot, { recursive: true });
- // Stub node_modules to mask any system-level @noble/ed25519 install.
- mkdirSync(join(isolatedRoot, 'node_modules'), { recursive: true });
-
- const out = spawnSync('node', [VERIFY, '--manifest', REAL_MANIFEST, '--root', isolatedRoot, '--json'], {
- encoding: 'utf8',
- env: { ...process.env, NODE_PATH: '' },
- });
-
- record(
- 'exit code is 2 (precondition), not 1',
- out.status === 2,
- `got exit=${out.status}, stdout=${out.stdout?.slice(0, 200)}, stderr=${out.stderr?.slice(0, 200)}`,
- );
- record(
- 'stderr names @noble/ed25519 and the fix command',
- /@noble\/ed25519/.test(out.stderr) && /npm (ci|install)/.test(out.stderr),
- `stderr=${out.stderr?.slice(0, 400)}`,
- );
- record(
- 'JSON output carries machine-parseable precondition tag',
- /noble-ed25519-not-installed/.test(out.stdout),
- `stdout=${out.stdout?.slice(0, 200)}`,
+function run(root, manifest = REAL_MANIFEST, ...extra) {
+ return spawnSync(
+ process.execPath,
+ [VERIFY, '--manifest', manifest, '--root', root, '--json', ...extra],
+ { encoding: 'utf8', env: { ...process.env, NODE_PATH: '' } },
);
-
- rmSync(tmp, { recursive: true, force: true });
}
-// ── Case 2: dist files missing β†’ exit 2 (precondition) ──────────────
-// Point verify.mjs at an isolated root that DOES have @noble/ed25519
-// reachable (symlinked from the real install), has source files copied
-// from the checkout, but has none of the manifest's dist/ files β€”
-// mimicking a clean clone with dependencies installed and no build run.
-console.log('\nCase 2: dist manifest files missing (source-only, deps installed)');
-{
- const tmp = mkdtempSync(join(tmpdir(), 'witness-smoke-nobuild-'));
- // Make @noble/ed25519 reachable by symlinking node_modules.
- const realNodeModules = resolve(REPO_ROOT, 'node_modules');
- if (existsSync(join(realNodeModules, '@noble', 'ed25519'))) {
- mkdirSync(join(tmp, 'node_modules', '@noble'), { recursive: true });
- // Use a relative symlink that survives the spawn.
- const src = join(realNodeModules, '@noble', 'ed25519');
- const dst = join(tmp, 'node_modules', '@noble', 'ed25519');
- try {
- // fs.symlinkSync via spawnSync to avoid extra import for the rare-path branch.
- spawnSync('ln', ['-s', src, dst]);
- } catch { /* best-effort */ }
+function parseOutput(out) {
+ try {
+ return JSON.parse(out.stdout);
+ } catch {
+ return null;
}
+}
+
+if (!existsSync(VERIFY) || !existsSync(REAL_MANIFEST)) {
+ console.error('smoke: verifier or signed manifest is missing');
+ process.exit(1);
+}
+
+const tmp = mkdtempSync(join(tmpdir(), 'witness-source-only-'));
+try {
+ const witness = JSON.parse(readFileSync(REAL_MANIFEST, 'utf8'));
+ const sourceFixes = witness.manifest.fixes.filter(
+ (fix) => !fix.file.split(/[\\/]/).includes('dist'),
+ );
+ const generatedFixes = witness.manifest.fixes.length - sourceFixes.length;
- const realManifest = JSON.parse(readFileSync(REAL_MANIFEST, 'utf8'));
- for (const fix of realManifest.manifest.fixes) {
- if (fix.file.includes('/dist/')) continue;
+ for (const fix of sourceFixes) {
const src = resolve(REPO_ROOT, fix.file);
const dst = resolve(tmp, fix.file);
if (!existsSync(src)) continue;
@@ -127,59 +72,75 @@ console.log('\nCase 2: dist manifest files missing (source-only, deps installed)
cpSync(src, dst);
}
- const out = spawnSync('node', [VERIFY, '--manifest', REAL_MANIFEST, '--root', tmp, '--json'], {
- encoding: 'utf8',
- });
-
- // We accept either:
- // - exit 2 with precondition=dist-not-built (the new behavior)
- // - exit 2 with precondition=noble-ed25519-not-installed (if the
- // symlink trick didn't satisfy the probe on this runner β€” also a
- // precondition, still not a real failure)
- // We do NOT accept exit 1 β€” that's the bug this guard exists to catch.
+ console.log('\nCase 1: source-only verification needs no installed dependency');
+ const sourceOnly = run(tmp, REAL_MANIFEST, '--source-only');
+ const sourceResult = parseOutput(sourceOnly);
record(
- 'exit code is 2 (precondition), not 1',
- out.status === 2,
- `got exit=${out.status}, stdout head=${out.stdout?.slice(0, 200)}, stderr head=${out.stderr?.slice(0, 200)}`,
+ 'signed manifest and all source markers verify',
+ sourceOnly.status === 0 && sourceResult?.ok === true,
+ `exit=${sourceOnly.status}, output=${(sourceOnly.stdout + sourceOnly.stderr).slice(0, 400)}`,
);
record(
- 'output carries a precondition tag',
- /dist-not-built/.test(out.stdout + out.stderr),
- `combined output=${(out.stdout + out.stderr).slice(0, 400)}`,
+ 'scope and skipped generated entries are explicit',
+ sourceResult?.scope === 'source-only'
+ && sourceResult?.summary?.skippedGenerated === generatedFixes
+ && sourceResult?.results?.length === sourceFixes.length,
+ `result=${JSON.stringify(sourceResult?.summary)}`,
+ );
+ record(
+ 'built-in cryptographic verifier was used',
+ sourceResult?.signature?.verifier === 'node:crypto'
+ && sourceResult?.signature?.signatureValid === true
+ && sourceResult?.signature?.publicKeyReproducible === true,
+ `signature=${JSON.stringify(sourceResult?.signature)}`,
);
- rmSync(tmp, { recursive: true, force: true });
-}
+ console.log('\nCase 2: signature tampering fails closed');
+ const tampered = structuredClone(witness);
+ tampered.integrity.signature =
+ `${tampered.integrity.signature[0] === '0' ? '1' : '0'}${tampered.integrity.signature.slice(1)}`;
+ const tamperedPath = join(tmp, 'tampered-manifest.json');
+ writeFileSync(tamperedPath, JSON.stringify(tampered));
+ const badSignature = run(tmp, tamperedPath, '--source-only');
+ record(
+ 'one-byte signature change exits 1',
+ badSignature.status === 1 && parseOutput(badSignature)?.signature?.signatureValid === false,
+ `exit=${badSignature.status}, output=${badSignature.stdout.slice(0, 300)}`,
+ );
-// ── Case 3: current checkout classification is explicit ─────────────
-// This CI job installs deps but intentionally does not build dist. Local
-// dev runs often have dist from a prior build. Accept either shape, but
-// require the machine-readable reason to be precise.
-console.log('\nCase 3: current checkout classification is explicit');
-{
- const out = spawnSync('node', [VERIFY, '--manifest', REAL_MANIFEST, '--json'], {
- encoding: 'utf8',
- cwd: REPO_ROOT,
- });
- if (out.status === 2) {
- record(
- 'exit 2 is specifically dist-not-built, not missing dependency',
- /"precondition":\s*"dist-not-built"/.test(out.stdout),
- `got exit=2, stdout=${out.stdout.slice(0, 300)}, stderr=${out.stderr.slice(0, 300)}`,
- );
+ console.log('\nCase 3: source marker regression fails closed');
+ const markerFix = sourceFixes.find((fix) => existsSync(resolve(tmp, fix.file)));
+ if (!markerFix) {
+ record('manifest has a locally present source entry', false);
} else {
+ const markerPath = resolve(tmp, markerFix.file);
+ const source = readFileSync(markerPath, 'utf8');
+ writeFileSync(markerPath, source.replace(markerFix.marker, 'ruflo-regressed-marker'));
+ const regression = run(tmp, REAL_MANIFEST, '--source-only');
+ const result = parseOutput(regression);
record(
- 'built/current tree verification actually ran',
- out.status === 0 || out.status === 1,
- `got exit=${out.status}, tail=${(out.stdout + out.stderr).slice(-300)}`,
+ 'missing source marker exits 1 and is classified regressed',
+ regression.status === 1 && result?.summary?.regressed >= 1,
+ `exit=${regression.status}, summary=${JSON.stringify(result?.summary)}`,
);
+ writeFileSync(markerPath, source);
}
+
+ console.log('\nCase 4: legacy full-tree verification retains precondition exit');
+ const full = run(tmp);
+ const fullResult = parseOutput(full);
+ record(
+ 'unbuilt full-tree verification exits 2',
+ full.status === 2 && fullResult?.precondition === 'dist-not-built',
+ `exit=${full.status}, output=${(full.stdout + full.stderr).slice(0, 300)}`,
+ );
+} finally {
+ rmSync(tmp, { recursive: true, force: true });
}
console.log('');
if (failures.length > 0) {
- console.error(`smoke-witness-verify-precondition: ${failures.length} check(s) failed:`);
- for (const f of failures) console.error(` - ${f}`);
+ console.error(`smoke-witness-verify-precondition: ${failures.length} check(s) failed`);
process.exit(1);
}
console.log('smoke-witness-verify-precondition: all checks passed');
diff --git a/v3/@claude-flow/cli-core/src/output.ts b/v3/@claude-flow/cli-core/src/output.ts
index 6a299418f9..9052a53923 100644
--- a/v3/@claude-flow/cli-core/src/output.ts
+++ b/v3/@claude-flow/cli-core/src/output.ts
@@ -162,6 +162,11 @@ export class OutputFormatter {
this.errorStream.write(text + '\n');
}
+ /** Whether transient terminal UI (spinners/progress redraws) is safe. */
+ supportsInteractiveOutput(): boolean {
+ return this.outputStream.isTTY === true;
+ }
+
// ============================================
// Formatted Output Methods
// ============================================
@@ -596,6 +601,10 @@ export class Spinner {
start(): void {
if (this.interval) return;
+ // Piped/redirected output has no cursor to redraw. Emitting frames there
+ // leaves literal carriage-return fragments before the first real result
+ // (#2814), so keep non-interactive output deterministic and silent.
+ if (!this.formatter.supportsInteractiveOutput()) return;
this.interval = setInterval(() => {
this.render();
@@ -612,8 +621,10 @@ export class Spinner {
this.interval = null;
}
- // Clear the line
- process.stdout.write('\r' + ' '.repeat(this.text.length + 10) + '\r');
+ if (this.formatter.supportsInteractiveOutput()) {
+ // Erase the entire terminal row, including ANSI-colored frame bytes.
+ this.formatter.write('\r\x1b[2K');
+ }
if (message) {
this.formatter.writeln(message);
@@ -630,7 +641,7 @@ export class Spinner {
private render(): void {
const frame = this.formatter.info(this.frames[this.frameIndex]);
- process.stdout.write(`\r${frame} ${this.text}`);
+ this.formatter.write(`\r${frame} ${this.text}`);
}
setText(text: string): void {
diff --git a/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json b/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json
index 6bd30fe75b..7e10f49750 100644
--- a/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json
+++ b/v3/@claude-flow/cli/.claude/helpers/helpers.manifest.json
@@ -1,13 +1,13 @@
{
"manifest": {
- "version": "3.32.35",
+ "version": "3.32.36",
"files": {
"auto-memory-hook.mjs": "68be7e9a9eba7bf9c4e8a230db7bf61a243b965639f8504842799d6c6ca28762",
- "hook-handler.cjs": "50ea92a72651bdc95634f7588d56a5870963168eef5226f66ed14af3b47c8d9a",
- "intelligence.cjs": "bd1f8e4b034944aee1df0391dc47ac2e8cc4b3aa542c65407a59d49620bbf76b",
- "statusline.cjs": "d2a0eac56d1267d8dbed2d70b09feb592299469196ec4b215909f2b052144882"
+ "hook-handler.cjs": "dae295fb9ae2626b89899c19a20cc911541af82b52d2eeb9b214d618b96e9a86",
+ "intelligence.cjs": "792c24a12704267e6b45ed0794e128131fb16e4174a43e65a5afe757bc0230af",
+ "statusline.cjs": "0457fe53f8cd2c56458ff178392536a5868efd1a573665fa43bc01d2d95ca677"
}
},
- "signature": "7hAABpKaZablL78ug8UW506P+ppwYlDb2qws0D4BbCeugfGQTdDEOYsndbZMc4+Wzbx10oQbnubqh8jHZnHvBQ==",
+ "signature": "qGxpst4ul6cizCQw1hjdJ5sBXj7uN7Fm1Dux2sKC7BwcPA66Nr9RzI8c8BJuKEUyPgaDtSvaY/gZTX2hWNqXBg==",
"algorithm": "ed25519"
}
diff --git a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs
index 1c5cca2ac8..b95cf1c308 100755
--- a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs
+++ b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs
@@ -286,6 +286,31 @@ async function readStdin() {
});
}
+function claimSideEffectEvent(family, stdinData, event) {
+ if (/^(1|true|yes|on)$/i.test(process.env.RUFLO_DISABLE_HOOK_DEDUP || '')) return true;
+ try {
+ const crypto = require('crypto');
+ const eventId = event?.tool_use_id || event?.toolUseId ||
+ event?.session_id || event?.sessionId || event?.hook_event_id;
+ const payloadIdentity = eventId
+ ? `event:${eventId}`
+ : `payload:${(stdinData || '').trim()}|bucket:${Math.floor(Date.now() / 2000)}`;
+ const projectRoot = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+ const digest = crypto.createHash('sha256')
+ .update(`ruflo-hook-dedup-v1\0${path.resolve(projectRoot)}\0${family}\0${payloadIdentity}`)
+ .digest('hex');
+ const dir = process.env.RUFLO_HOOK_DEDUP_DIR ||
+ path.join(os.tmpdir(), 'ruflo-hook-dedup-v1');
+ fs.mkdirSync(dir, { recursive: true });
+ const fd = fs.openSync(path.join(dir, digest), 'wx', 0o600);
+ fs.writeFileSync(fd, String(Date.now()));
+ fs.closeSync(fd);
+ return true;
+ } catch (error) {
+ return error?.code === 'EEXIST' ? false : true;
+ }
+}
+
async function main() {
// Global safety timeout: hooks must NEVER hang (#1530, #1531)
const safetyTimer = setTimeout(() => {
@@ -302,6 +327,11 @@ async function main() {
try { hookInput = JSON.parse(stdinData); } catch (e) { /* ignore parse errors */ }
}
+ if ((command === 'post-edit' || command === 'session-end') &&
+ !claimSideEffectEvent(command, stdinData, hookInput)) {
+ return;
+ }
+
// Normalize snake_case/camelCase: Claude Code sends tool_input/tool_name (snake_case)
const toolInput = hookInput.toolInput || hookInput.tool_input || {};
const toolName = hookInput.toolName || hookInput.tool_name || '';
diff --git a/v3/@claude-flow/cli/.claude/helpers/intelligence.cjs b/v3/@claude-flow/cli/.claude/helpers/intelligence.cjs
index 5f3d6d3905..cd6e720c84 100755
--- a/v3/@claude-flow/cli/.claude/helpers/intelligence.cjs
+++ b/v3/@claude-flow/cli/.claude/helpers/intelligence.cjs
@@ -17,12 +17,30 @@
const fs = require('fs');
const path = require('path');
-const DATA_DIR = path.join(process.cwd(), '.claude-flow', 'data');
+function resolveProjectRoot(startDir) {
+ if (process.env.CLAUDE_PROJECT_DIR) {
+ return path.resolve(process.env.CLAUDE_PROJECT_DIR);
+ }
+ let dir = path.resolve(startDir || process.cwd());
+ while (true) {
+ if (fs.existsSync(path.join(dir, '.git')) ||
+ fs.existsSync(path.join(dir, '.claude-flow'))) {
+ return dir;
+ }
+ const parent = path.dirname(dir);
+ if (parent === dir) return path.resolve(startDir || process.cwd());
+ dir = parent;
+ }
+}
+
+const PROJECT_ROOT = resolveProjectRoot(process.cwd());
+const DATA_DIR = path.join(PROJECT_ROOT, '.claude-flow', 'data');
const STORE_PATH = path.join(DATA_DIR, 'auto-memory-store.json');
const GRAPH_PATH = path.join(DATA_DIR, 'graph-state.json');
const RANKED_PATH = path.join(DATA_DIR, 'ranked-context.json');
const PENDING_PATH = path.join(DATA_DIR, 'pending-insights.jsonl');
-const SESSION_DIR = path.join(process.cwd(), '.claude-flow', 'sessions');
+const LEGACY_PENDING_PATH = path.join(process.cwd(), '.claude-flow', 'data', 'pending-insights.jsonl');
+const SESSION_DIR = path.join(PROJECT_ROOT, '.claude-flow', 'sessions');
const SESSION_FILE = path.join(SESSION_DIR, 'current.json');
// ── Safety limits (fixes #1530, #1531) ─────────────────────────────────────
@@ -47,6 +65,22 @@ const STOP_WORDS = new Set([
function ensureDataDir() {
if (!fs.existsSync(DATA_DIR)) fs.mkdirSync(DATA_DIR, { recursive: true });
+ // Recover signal written by older helpers under a subdirectory cwd. Keep
+ // the legacy file intact and append only lines not already present.
+ if (path.resolve(LEGACY_PENDING_PATH) !== path.resolve(PENDING_PATH) &&
+ fs.existsSync(LEGACY_PENDING_PATH)) {
+ try {
+ const existing = fs.existsSync(PENDING_PATH)
+ ? new Set(fs.readFileSync(PENDING_PATH, 'utf-8').split('\n').filter(Boolean))
+ : new Set();
+ const recovered = fs.readFileSync(LEGACY_PENDING_PATH, 'utf-8')
+ .split('\n')
+ .filter(line => line && !existing.has(line));
+ if (recovered.length > 0) {
+ fs.appendFileSync(PENDING_PATH, recovered.join('\n') + '\n', 'utf-8');
+ }
+ } catch { /* migration is best-effort; never block hook execution */ }
+ }
}
function readJSON(filePath) {
@@ -300,7 +334,7 @@ function buildEdges(entries) {
*/
function bootstrapFromMemoryFiles() {
const entries = [];
- const cwd = process.cwd();
+ const cwd = PROJECT_ROOT;
// Search for auto-memory directories
const candidates = [
@@ -1032,7 +1066,16 @@ function stats(outputJson) {
return report;
}
-module.exports = { init, getContext, recordEdit, feedback, consolidate, stats };
+module.exports = {
+ init,
+ getContext,
+ recordEdit,
+ feedback,
+ consolidate,
+ stats,
+ resolveProjectRoot,
+ projectRoot: PROJECT_ROOT,
+};
// ── CLI entrypoint ──────────────────────────────────────────────────────────
if (require.main === module) {
diff --git a/v3/@claude-flow/cli/.claude/helpers/statusline.cjs b/v3/@claude-flow/cli/.claude/helpers/statusline.cjs
index 1be517a685..bcf8fbe41c 100644
--- a/v3/@claude-flow/cli/.claude/helpers/statusline.cjs
+++ b/v3/@claude-flow/cli/.claude/helpers/statusline.cjs
@@ -42,7 +42,11 @@ const CONFIG = {
hideCost: /^(1|true|yes|on)$/i.test(process.env.RUFLO_STATUSLINE_HIDE_COST || ''),
};
-const CWD = process.cwd();
+const CWD = process.env.CLAUDE_PROJECT_DIR || process.cwd();
+// Replaced by statusline-generator with the package root of the CLI that
+// installed this helper. This survives custom npm prefixes and bundled Node
+// runtimes whose process.execPath belongs to a different tree (#2811).
+const BAKED_INSTALL_ROOT = "";
// ─── Delegation cache ───────────────────────────────────────────
// Cache the CLI JSON result so rapid prompt re-renders (Claude Code
@@ -404,6 +408,154 @@ function getLocalIntegration() {
return integration;
}
+// ─── Security freshness overlay (ruvnet/ruflo#2776) ──────────────
+// The shipped CLI producer (dist/src/funnel/local-signals.js getSecurityStatus)
+// only ever emits PENDING / CLEAN / ISSUES β€” it captures `scannedAt` but never
+// inspects it, so a year-old scan renders πŸ›‘ βœ“ forever and the renderer's
+// STALE / IN_PROGRESS branches are unreachable. Worse, when CLI delegation
+// fails, the stale-while-revalidate cache (readCache() below) keeps serving
+// the pre-scan PENDING pill indefinitely, so a user who runs the advertised
+// `ruflo security scan` sees no change β€” the pill freezes at "scan pending".
+//
+// This overlay recomputes the security block from disk on EVERY render (same
+// pattern as adrs/agentdb/tests/hooks above), which:
+// 1) Makes STALE reachable β€” when the newest scan is older than
+// RUFLO_SCAN_STALE_HOURS (default 24h β€” matches the CVE feed refresh
+// cadence), report STALE regardless of what the cached CLI JSON says.
+// 2) Makes IN_PROGRESS reachable β€” when a `scan-in-progress` marker file
+// exists and is younger than SECURITY_IN_PROGRESS_MAX_MIN (guards against
+// a crashed scan leaving the marker behind).
+// 3) Caps the "scan pending" display window β€” if PENDING has been shown for
+// >RUFLO_SCAN_PENDING_CAP_MIN (default 30) without a completion write,
+// switch to STALE and stop rendering the yellow indicator. The tracker
+// lives in ~/.ruflo/statusline-scan-pending-since.json, keyed by CWD
+// hash so multiple project checkouts don't collide.
+// 4) Since this runs AFTER readCache() serves stale data, it bypasses the
+// "pill freezes at PENDING" freeze in defect 2 β€” the overlay reads
+// fresh disk state even when the CLI delegation is broken.
+const SECURITY_STALE_HOURS = Math.max(1, parseInt(process.env.RUFLO_SCAN_STALE_HOURS || '24', 10) || 24);
+const SECURITY_PENDING_CAP_MIN = Math.max(1, parseInt(process.env.RUFLO_SCAN_PENDING_CAP_MIN || '30', 10) || 30);
+const SECURITY_IN_PROGRESS_MAX_MIN = 30; // marker older than this = crashed scan; treat as absent
+const PENDING_TRACK_FILE = path.join(os.homedir(), '.ruflo', 'statusline-scan-pending-since.json');
+const CWD_KEY = require('crypto').createHash('md5').update(CWD).digest('hex').slice(0, 12);
+
+function readPendingSince() {
+ try {
+ if (!fs.existsSync(PENDING_TRACK_FILE)) return null;
+ const raw = JSON.parse(fs.readFileSync(PENDING_TRACK_FILE, 'utf-8'));
+ if (raw && typeof raw === 'object' && typeof raw[CWD_KEY] === 'number') return raw[CWD_KEY];
+ } catch { /* ignore */ }
+ return null;
+}
+
+function writePendingSince(ts) {
+ try {
+ let obj = {};
+ if (fs.existsSync(PENDING_TRACK_FILE)) {
+ try { obj = JSON.parse(fs.readFileSync(PENDING_TRACK_FILE, 'utf-8')) || {}; } catch { obj = {}; }
+ }
+ if (ts === null) { delete obj[CWD_KEY]; } else { obj[CWD_KEY] = ts; }
+ fs.mkdirSync(path.dirname(PENDING_TRACK_FILE), { recursive: true, mode: 0o700 });
+ fs.writeFileSync(PENDING_TRACK_FILE, JSON.stringify(obj), { encoding: 'utf-8', mode: 0o600 });
+ } catch { /* ignore */ }
+}
+
+function getLocalSecurity(cliSecurity) {
+ const base = (cliSecurity && typeof cliSecurity === 'object')
+ ? Object.assign({}, cliSecurity)
+ : { status: 'NONE', findings: 0, cvesFixed: 0, totalCves: 0 };
+ base.findings = Math.max(0, base.findings || 0);
+
+ const scanDir = path.join(CWD, '.claude', 'security-scans');
+
+ // Detect a live in-progress marker (writer opts-in by writing this file).
+ let inProgress = false;
+ try {
+ const marker = path.join(scanDir, 'scan-in-progress');
+ if (fs.existsSync(marker)) {
+ const ageMin = (Date.now() - fs.statSync(marker).mtimeMs) / 60000;
+ if (ageMin < SECURITY_IN_PROGRESS_MAX_MIN) inProgress = true;
+ }
+ } catch { /* ignore */ }
+
+ // Find newest scan-*.json by mtime and read its findings/timestamp.
+ let newestPath = null;
+ let newestMtime = 0;
+ try {
+ if (fs.existsSync(scanDir)) {
+ for (const name of fs.readdirSync(scanDir)) {
+ if (!name.startsWith('scan-') || !name.endsWith('.json')) continue;
+ try {
+ const st = fs.statSync(path.join(scanDir, name));
+ if (st.mtimeMs > newestMtime) { newestMtime = st.mtimeMs; newestPath = path.join(scanDir, name); }
+ } catch { /* ignore */ }
+ }
+ }
+ } catch { /* ignore */ }
+
+ if (newestPath) {
+ // We have a scan on disk β€” the never-scanned pending tracker is no longer
+ // relevant. Clear it so a re-created directory can start a fresh window.
+ writePendingSince(null);
+
+ let scannedAtMs = newestMtime;
+ let findings = base.findings;
+ try {
+ const j = JSON.parse(fs.readFileSync(newestPath, 'utf-8'));
+ // scannedAt (CLI producer's field name) OR timestamp (writer's field name).
+ const isoStr = (j && (j.scannedAt || j.timestamp)) || null;
+ if (isoStr) {
+ const t = Date.parse(isoStr);
+ if (!isNaN(t)) scannedAtMs = t;
+ }
+ // findings may be a number, an array, or nested in summary.total.
+ if (j) {
+ if (typeof j.findings === 'number') findings = j.findings;
+ else if (Array.isArray(j.findings)) findings = j.findings.length;
+ else if (j.summary && typeof j.summary.total === 'number') findings = j.summary.total;
+ }
+ } catch { /* ignore parse β€” fall back to mtime + cached findings */ }
+
+ base.findings = Math.max(0, findings || 0);
+ base.scannedAt = new Date(scannedAtMs).toISOString();
+
+ const ageHours = (Date.now() - scannedAtMs) / 3600000;
+ if (ageHours >= SECURITY_STALE_HOURS) {
+ // Stale but findings still render red (a year-old ISSUES scan is still bad).
+ base.status = 'STALE';
+ } else if (inProgress) {
+ base.status = 'IN_PROGRESS';
+ } else if (base.findings > 0) {
+ base.status = 'ISSUES';
+ } else {
+ base.status = 'CLEAN';
+ }
+ return base;
+ }
+
+ // No scan file. If a live marker exists, we're mid-scan.
+ if (inProgress) {
+ base.status = 'IN_PROGRESS';
+ // Reset the pending tracker so, if the scan crashes mid-flight, the next
+ // render starts a fresh N-minute pending window instead of an already-expired one.
+ writePendingSince(null);
+ return base;
+ }
+
+ // Truly never-scanned: track how long we've shown PENDING. After the cap,
+ // escalate to STALE with the dim/gray glyph so the pill visibly stops
+ // shouting for attention β€” the user has either ignored it for 30 min or
+ // the scan is silently failing to write.
+ let pendingSince = readPendingSince();
+ if (pendingSince === null || typeof pendingSince !== 'number') {
+ pendingSince = Date.now();
+ writePendingSince(pendingSince);
+ }
+ const pendingAgeMin = (Date.now() - pendingSince) / 60000;
+ base.status = (pendingAgeMin >= SECURITY_PENDING_CAP_MIN) ? 'STALE' : 'PENDING';
+ return base;
+}
+
// Overlay every locally-derived block onto the CLI data (mutates in place).
function applyLocalOverlays(data) {
data.adrs = getLocalADRCount();
@@ -411,6 +563,9 @@ function applyLocalOverlays(data) {
data.tests = getLocalTests();
data.hooks = getLocalHooks();
data.integration = getLocalIntegration();
+ // Security overlay: recompute freshness from disk on every render so cached
+ // CLI JSON can never freeze the pill at PENDING. See getLocalSecurity() above.
+ data.security = getLocalSecurity(data.security);
return data;
}
@@ -685,6 +840,7 @@ function getPkgVersion() {
try {
const home = os.homedir();
const pkgPaths = [
+ ...(BAKED_INSTALL_ROOT ? [path.join(BAKED_INSTALL_ROOT, 'package.json')] : []),
path.join(home, '.claude', 'plugins', 'marketplaces', 'ruflo', 'package.json'),
path.join(CWD, 'node_modules', '@claude-flow', 'cli', 'package.json'),
path.join(CWD, 'node_modules', 'ruflo', 'package.json'),
@@ -712,7 +868,12 @@ function getPkgVersion() {
// #2221 follow-up: a custom npm prefix (e.g. ~/.npm-global) is decoupled from
// the node binary location, so the binDir-derived probes above all miss. Also
// probe the npm prefix from the environment and the common ~/.npm-global default.
- for (const prefix of [process.env.npm_config_prefix, process.env.PREFIX, path.join(home, '.npm-global')]) {
+ for (const prefix of [
+ process.env.npm_config_prefix,
+ process.env.PREFIX,
+ path.join(home, '.local'),
+ path.join(home, '.npm-global'),
+ ]) {
if (prefix) globalModuleDirs.push(path.join(prefix, 'lib', 'node_modules'));
}
for (const gm of globalModuleDirs) {
@@ -731,14 +892,12 @@ function getPkgVersion() {
// right after a publish). Taking the first EXISTING candidate meant the
// header could show a stale version even when a newer install (e.g.
// node_modules/@claude-flow/cli from a plain npm install) was sitting right there.
- let found = false;
for (const p of pkgPaths) {
if (!fs.existsSync(p)) continue;
try {
const pkg = JSON.parse(fs.readFileSync(p, 'utf-8'));
if (pkg && typeof pkg.version === 'string' && pkg.version.length > 0) {
- if (!found || compareVersions(pkg.version, ver) > 0) ver = pkg.version;
- found = true;
+ if (compareVersions(pkg.version, ver) > 0) ver = pkg.version;
}
} catch { /* ignore */ }
}
@@ -851,10 +1010,14 @@ function generateStatusline() {
if (healthAllGreen) {
opsParts.push(c.brightGreen + 'πŸ›‘ βœ“' + c.reset);
} else {
+ // #2776: STALE gets dim/gray (distinct from the actionable yellow of
+ // PENDING/IN_PROGRESS) so a stale pill visibly stops shouting for
+ // attention β€” the user can act on the "run ruflo security scan" prompt or
+ // ignore it without a permanently-yellow indicator.
if (secStatus === 'PENDING') opsParts.push(c.brightYellow + 'πŸ›‘ scan pending' + c.reset);
else if (secStatus === 'IN_PROGRESS') opsParts.push(c.brightYellow + 'πŸ›‘ scanning…' + c.reset);
else if (secStatus === 'ISSUES') opsParts.push(c.brightRed + 'πŸ›‘ findings' + c.reset);
- else if (secStatus === 'STALE') opsParts.push(c.brightYellow + 'πŸ›‘ scan stale' + c.reset);
+ else if (secStatus === 'STALE') opsParts.push(c.dim + 'πŸ›‘ scan stale' + c.reset);
else if (secStatus !== 'NONE' && secStatus !== 'CLEAN') opsParts.push(c.brightRed + 'πŸ›‘ ' + secStatus.toLowerCase() + c.reset);
if (findings > 0) {
opsParts.push(c.brightRed + '⚠ ' + findings + ' finding' + (findings === 1 ? '' : 's') + c.reset);
diff --git a/v3/@claude-flow/cli/README.md b/v3/@claude-flow/cli/README.md
index 284d81196f..da378f4ecd 100644
--- a/v3/@claude-flow/cli/README.md
+++ b/v3/@claude-flow/cli/README.md
@@ -193,6 +193,20 @@ npm install -g ruflo@latest
claude mcp add ruflo -- npx ruflo@latest mcp start
```
+Small-context backends can advertise only the tool categories they need:
+
+```bash
+CLAUDE_FLOW_MCP_TOOLS=memory,swarm,agent,hooks \
+ npx ruflo@latest mcp start
+
+# Optional: lets `ruflo doctor -c mcp-overhead` compare the live schema
+# estimate with the backend's real context limit.
+CLAUDE_FLOW_CONTEXT_WINDOW_TOKENS=32000 ruflo doctor -c mcp-overhead
+```
+
+The default remains `all` for backwards compatibility. Selectors accept
+categories, namespace prefixes, or exact tool names.
+
---
## What You Get
diff --git a/v3/@claude-flow/cli/__tests__/doctor-2677-reflexion.test.ts b/v3/@claude-flow/cli/__tests__/doctor-2677-reflexion.test.ts
new file mode 100644
index 0000000000..3fd6b44940
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/doctor-2677-reflexion.test.ts
@@ -0,0 +1,85 @@
+/**
+ * Regression guard for #2677's unreachable Reflexion substrate.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { doctorCommand } from '../src/commands/doctor.js';
+import { _resetMemoryRootCache } from '../src/memory/memory-initializer.js';
+
+type HealthCheck = { name: string; status: 'pass' | 'warn' | 'fail'; message: string };
+type DoctorData = { results: HealthCheck[] };
+
+const ORIGINAL_CWD = process.cwd();
+let workdir: string;
+
+async function runMemoryDoctor(): Promise<HealthCheck[]> {
+ const ctx = {
+ flags: { component: 'memory' },
+ args: [],
+ config: {},
+ } as unknown as Parameters<NonNullable<typeof doctorCommand.action>>[0];
+ const result = await doctorCommand.action!(ctx);
+ return (result.data as DoctorData).results;
+}
+
+function find(results: HealthCheck[], name: string): HealthCheck | undefined {
+ return results.find((result) => result.name === name);
+}
+
+async function seed(includeEmbedding: boolean, includeCritique: boolean): Promise<void> {
+ const Database = (await import('better-sqlite3')).default as any;
+ mkdirSync(join(workdir, '.swarm'), { recursive: true });
+ const db = new Database(join(workdir, '.swarm', 'memory.db'));
+ db.exec(`
+ CREATE TABLE memory_entries (
+ id TEXT PRIMARY KEY, content TEXT, embedding TEXT
+ );
+ INSERT INTO memory_entries VALUES ('m1', 'execution feedback', '[1,0]');
+ CREATE TABLE episodes (
+ id INTEGER PRIMARY KEY AUTOINCREMENT,
+ session_id TEXT NOT NULL, task TEXT NOT NULL, critique TEXT
+ );
+ CREATE TABLE episode_embeddings (
+ episode_id INTEGER PRIMARY KEY, embedding BLOB NOT NULL
+ );
+ `);
+ db.prepare('INSERT INTO episodes (session_id, task, critique) VALUES (?,?,?)')
+ .run('distill:feedback', 'test auth', includeCritique ? 'validation failed before fix' : null);
+ if (includeEmbedding) {
+ db.prepare('INSERT INTO episode_embeddings (episode_id, embedding) VALUES (?,?)')
+ .run(1, Buffer.from(Float32Array.from([1, 0]).buffer));
+ }
+ db.close();
+}
+
+describe('doctor #2677 β€” Reflexion and critique coverage', () => {
+ beforeEach(() => {
+ workdir = mkdtempSync(join(tmpdir(), 'doctor-2677-reflexion-'));
+ process.chdir(workdir);
+ _resetMemoryRootCache();
+ });
+
+ afterEach(() => {
+ process.chdir(ORIGINAL_CWD);
+ _resetMemoryRootCache();
+ rmSync(workdir, { recursive: true, force: true });
+ });
+
+ it('fails when episodes are structurally unreachable and carry no critique', async () => {
+ await seed(false, false);
+ const results = await runMemoryDoctor();
+ expect(find(results, 'Memory Reflexion Coverage')?.status).toBe('fail');
+ expect(find(results, 'Memory Reflexion Coverage')?.message).toContain('0/1');
+ expect(find(results, 'Memory Feedback Critiques')?.status).toBe('fail');
+ });
+
+ it('passes when every feedback episode is embedded and carries a lesson', async () => {
+ await seed(true, true);
+ const results = await runMemoryDoctor();
+ expect(find(results, 'Memory Reflexion Coverage')?.status).toBe('pass');
+ expect(find(results, 'Memory Feedback Critiques')?.status).toBe('pass');
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/doctor-2677-stale-settings.test.ts b/v3/@claude-flow/cli/__tests__/doctor-2677-stale-settings.test.ts
new file mode 100644
index 0000000000..afc3306503
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/doctor-2677-stale-settings.test.ts
@@ -0,0 +1,100 @@
+/**
+ * Regression guard for #2677's stale-settings finding: every
+ * `npx @claude-flow/cli@latest <subcommand>` in Claude settings has the same
+ * cold-process cost, not only the historical `hooks` form.
+ */
+import { afterEach, beforeEach, describe, expect, it } from 'vitest';
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { doctorCommand } from '../src/commands/doctor.js';
+import { executeUpgrade } from '../src/init/executor.js';
+
+type HealthCheck = { name: string; status: 'pass' | 'warn' | 'fail'; message: string };
+type DoctorData = { results: HealthCheck[] };
+
+const ORIGINAL_CWD = process.cwd();
+const ORIGINAL_HOME = process.env.HOME;
+let workdir: string;
+
+async function runStaleSettingsCheck(): Promise<HealthCheck> {
+ const ctx = {
+ flags: { component: 'stale-settings' },
+ args: [],
+ config: {},
+ } as unknown as Parameters<NonNullable<typeof doctorCommand.action>>[0];
+ const result = await doctorCommand.action!(ctx);
+ return (result.data as DoctorData).results[0];
+}
+
+function writeSettings(settings: unknown): void {
+ mkdirSync(join(workdir, '.claude'), { recursive: true });
+ writeFileSync(join(workdir, '.claude', 'settings.json'), JSON.stringify(settings));
+}
+
+describe('doctor #2677 β€” stale npx detection covers every subcommand', () => {
+ beforeEach(() => {
+ workdir = mkdtempSync(join(tmpdir(), 'doctor-2677-settings-'));
+ process.chdir(workdir);
+ // Keep the test isolated from a developer's real ~/.claude/settings.json.
+ process.env.HOME = join(workdir, 'home');
+ });
+
+ afterEach(() => {
+ process.chdir(ORIGINAL_CWD);
+ if (ORIGINAL_HOME === undefined) delete process.env.HOME;
+ else process.env.HOME = ORIGINAL_HOME;
+ rmSync(workdir, { recursive: true, force: true });
+ });
+
+ it.each(['memory store --namespace notifications', 'daemon start --quiet', 'swarm status'])(
+ 'fails on npx @latest %s',
+ async (subcommand) => {
+ writeSettings({
+ hooks: {
+ Notification: [{ hooks: [{ command: `npx @claude-flow/cli@latest ${subcommand}` }] }],
+ },
+ });
+ const check = await runStaleSettingsCheck();
+ expect(check.status).toBe('fail');
+ expect(check.message).toContain('CRITICAL');
+ },
+ );
+
+ it('does not flag the generated local helper command', async () => {
+ writeSettings({
+ statusLine: { command: 'node .claude/helpers/statusline.cjs' },
+ });
+ expect((await runStaleSettingsCheck()).status).toBe('pass');
+ });
+
+ it('upgrade removes sibling npx hooks and regenerates the statusline', async () => {
+ writeSettings({
+ statusLine: { command: 'npx @claude-flow/cli@latest memory retrieve --key status' },
+ hooks: {
+ Notification: [{
+ hooks: [
+ { command: 'npx @claude-flow/cli@latest memory store --namespace notifications' },
+ { command: 'node custom-notification.cjs' },
+ ],
+ }],
+ PreToolUse: [{
+ hooks: [{ command: 'npx @claude-flow/cli@latest hooks pre-bash' }],
+ }],
+ },
+ });
+
+ const upgraded = await executeUpgrade(workdir, true);
+ expect(upgraded.success).toBe(true);
+ const settings = JSON.parse(readFileSync(join(workdir, '.claude', 'settings.json'), 'utf8'));
+ expect(settings.statusLine.command).toContain('.claude/helpers/statusline.cjs');
+ const commands = Object.values(settings.hooks)
+ .flatMap((groups: any) => groups.flatMap((group: any) => group.hooks ?? []))
+ .map((hook: any) => hook.command)
+ .filter(Boolean);
+ expect(commands.some((command: string) => command.includes('@claude-flow/cli@latest'))).toBe(false);
+ expect(commands).toContain('node custom-notification.cjs');
+ expect(commands.some((command: string) => command.includes('hook-handler.cjs') && command.includes('pre-bash'))).toBe(true);
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/funnel.test.ts b/v3/@claude-flow/cli/__tests__/funnel.test.ts
index 20d3e06b39..a9c63b666f 100644
--- a/v3/@claude-flow/cli/__tests__/funnel.test.ts
+++ b/v3/@claude-flow/cli/__tests__/funnel.test.ts
@@ -99,9 +99,9 @@ beforeEach(() => {
/**
* Seed the local remote-message cache exactly the way message-transport.ts's
- * writeCache() would after a successful GET /v1/messages β€” ADR-311 makes
- * this the ONLY content source (MESSAGES ships empty), so every test that
- * exercises rotation/disclosure must seed this cache first.
+ * writeCache() would after a successful GET /v1/messages. The remote pool is
+ * authoritative and overrides the in-code seed pool by id, so tests that need
+ * remote-specific content seed this cache; cold-start tests deliberately do not.
*/
function seedRemoteMessages(messages: unknown[]): void {
fs.writeFileSync(
@@ -191,12 +191,12 @@ describe('message content boundaries (ADR-301)', () => {
expect(isAllowedUrl('not a url')).toBe(false);
});
- it('ships ZERO local messages (ADR-311 "zero local promo content" guarantee)', () => {
- // The in-code MESSAGES pool is intentionally empty β€” all rotation
- // content (tips, promos, disclosure) is remote-sourced. This test
- // pins that guarantee; a future PR that adds a local message back
- // in must consciously fail this test to do so.
- expect(MESSAGES).toEqual([]);
+ it('ships a bounded, self-validating local seed pool (cold-start fallback)', () => {
+ expect(MESSAGES.length).toBeGreaterThan(0);
+ for (const message of MESSAGES) expect(isValidMessage(message)).toBe(true);
+ expect(MESSAGES.filter((message) => message.class === 'disclosure')).toHaveLength(1);
+ expect(MESSAGES.filter((message) => message.class === 'promotional')).toHaveLength(1);
+ expect(MESSAGES.every((message) => message.id.startsWith('local.'))).toBe(true);
});
it('a disclosure-class message without the manage tail is rejected, never repaired', () => {
@@ -205,10 +205,11 @@ describe('message content boundaries (ADR-301)', () => {
expect(isValidMessage({ ...base, text: '✨ Has it · manage: ruflo settings' })).toBe(true);
});
- it('selectDisclosureMessage returns null when no remote disclosure pool is cached (fail-closed)', () => {
- // No seedRemoteMessages() call β€” cache is empty, matching a cold start
- // or an unreachable remote feed. Per ADR-311, this means "show nothing".
- expect(selectDisclosureMessage(new Date())).toBeNull();
+ it('selectDisclosureMessage uses the local seed disclosure on cold start', () => {
+ const message = selectDisclosureMessage(new Date());
+ expect(message).not.toBeNull();
+ expect(message!.id).toBe('local.disclosure.v1');
+ expect(message!.class).toBe('disclosure');
});
it('selectDisclosureMessage is deterministic per 5-minute slot once seeded', () => {
@@ -216,22 +217,24 @@ describe('message content boundaries (ADR-301)', () => {
const t0 = new Date('2026-07-10T12:00:00.000Z');
const t0plus1s = new Date(t0.getTime() + 1000);
expect(selectDisclosureMessage(t0)?.id).toBe(selectDisclosureMessage(t0plus1s)?.id);
+ const poolSize =
+ TEST_DISCLOSURE_POOL.length + MESSAGES.filter((message) => message.class === 'disclosure').length;
const seen = new Set<string>();
- for (let i = 0; i < TEST_DISCLOSURE_POOL.length * 2; i++) {
+ for (let i = 0; i < poolSize * 2; i++) {
seen.add(selectDisclosureMessage(new Date(t0.getTime() + i * DISCLOSURE_ROTATION_SLOT_MS))?.id ?? '');
}
- // Rotation must cover every variant.
- expect(seen.size).toBe(TEST_DISCLOSURE_POOL.length);
+ expect(seen.size).toBe(poolSize);
});
});
// ─── ADR-301: rotation ratio ────────────────────────────────────────────────
describe('rotation scheduler (ADR-301 content ratio)', () => {
- it('returns null when no remote pool is cached (fail-closed, ADR-311)', () => {
- // No seedRemoteMessages() call β€” MESSAGES ships empty, so an unseeded
- // cache means nothing to rotate through. This is deliberate, not a bug.
- expect(selectMessage(new Date())).toBeNull();
+ it('uses bounded local seed content when no remote pool is cached', () => {
+ const message = selectMessage(new Date());
+ expect(message).not.toBeNull();
+ expect(message!.id.startsWith('local.')).toBe(true);
+ expect(['educational', 'promotional']).toContain(message!.class);
});
it('promotional content appears only in 1-of-5 slots and honors the 30-min cap', () => {
@@ -359,15 +362,19 @@ describe('promo orchestrator (getFunnelPromo)', () => {
expect(getFunnelPromo({ interactive: true, env: { ...process.env, RUFLO_FUNNEL: '0' } })).toBeNull();
});
- it('renders nothing on first render when no remote pool is cached (fail-closed, ADR-311)', () => {
- // No seedRemoteMessages() β€” this is a cold start or an unreachable API.
- // Zero local content means zero row, not a fallback to hardcoded text.
- expect(getFunnelPromo({ interactive: true, cwd: stateDir })).toBeNull();
+ it('first render uses the local seed disclosure when no remote pool is cached', () => {
+ const row = getFunnelPromo({ interactive: true, cwd: stateDir });
+ expect(row).not.toBeNull();
+ expect(row!.kind).toBe('disclosure');
+ expect(row!.text).toBe(
+ 'Ruflo shows occasional tips and sponsor notes here Β· manage: ruflo settings',
+ );
});
it('first interactive render is the disclosure, never a promotion', () => {
seedRemoteMessages(TEST_DISCLOSURE_POOL);
- const row = getFunnelPromo({ interactive: true, cwd: stateDir });
+ const now = new Date(Date.UTC(2026, 6, 10, 12, 0, 0));
+ const row = getFunnelPromo({ interactive: true, cwd: stateDir, now });
expect(row).not.toBeNull();
expect(row!.kind).toBe('disclosure');
// Row text is one of the seeded disclosure variants.
@@ -391,7 +398,7 @@ describe('promo orchestrator (getFunnelPromo)', () => {
it('keeps showing the disclosure through the grace window, then rotates messages', () => {
seedRemoteMessages([...TEST_DISCLOSURE_POOL, ...TEST_ROTATION_POOL]);
- const t0 = new Date();
+ const t0 = new Date(Date.UTC(2026, 6, 10, 12, 0, 0));
recordDisclosureShown(t0);
const during = getFunnelPromo({ interactive: true, cwd: stateDir, now: new Date(t0.getTime() + 1000) });
expect(during!.kind).toBe('disclosure');
@@ -1074,7 +1081,7 @@ describe('sponsored-downtime priority override (ADR-313)', () => {
const after = new Date(t0.getTime() + DISCLOSURE_GRACE_MS + 60_000);
const row = getFunnelPromo({ interactive: true, cwd: stateDir, now: after });
expect(row).not.toBeNull();
- expect(row!.text).not.toMatch(/sponsor/i);
+ expect(row!.text).not.toContain('ruflo proxy sponsor');
});
it('shows the enable-CTA when rate-limited without sponsored consent', () => {
diff --git a/v3/@claude-flow/cli/__tests__/hooks-metrics-swarm-backup-2797-2798-2799.test.ts b/v3/@claude-flow/cli/__tests__/hooks-metrics-swarm-backup-2797-2798-2799.test.ts
index 17fe01483b..414ec7e20c 100644
--- a/v3/@claude-flow/cli/__tests__/hooks-metrics-swarm-backup-2797-2798-2799.test.ts
+++ b/v3/@claude-flow/cli/__tests__/hooks-metrics-swarm-backup-2797-2798-2799.test.ts
@@ -40,9 +40,18 @@ describe('#2797 hooks metrics Pattern Learning counts real writes', () => {
try {
run(['memory', 'init'], wd);
run(['hooks', 'post-task', '-i', 't1', '--success', 'true', '-q', '0.95', '--task', 'some task', '--agent', 'coder', '--store-results'], wd);
+ run(['hooks', 'post-task', '-i', 't2', '--success', 'false', '-q', '0.2', '--task', 'failed task', '--agent', 'coder', '--store-results'], wd);
const { stdout } = run(['hooks', 'metrics', '--format', 'json'], wd);
const data = JSON.parse(stdout.slice(stdout.indexOf('{')));
- expect(data.patterns.total).toBeGreaterThan(0);
+ expect(data.patterns.total).toBe(2);
+ expect(data.patterns.successful).toBe(1);
+ expect(data.patterns.failed).toBe(1);
+ expect(data.patterns.successful + data.patterns.failed).toBeLessThanOrEqual(data.patterns.total);
+ expect(data.patterns.described).toBe(2);
+ expect(data.patterns.descriptionCoverage).toBe(1);
+ expect(data.agents.routingAccuracy).toBeNull();
+ expect(data.agents.averageConfidence).toBeGreaterThan(0);
+ expect(data.agents.outcomeSuccessRate).toBe(0.5);
} finally {
try { rmSync(wd, { recursive: true, force: true }); } catch { /* */ }
}
@@ -84,6 +93,10 @@ describe('#2799 swarm status reflects spawned agents', () => {
// The Agents section's Total must now be 4, not 0. Match the "Total | 4"
// row in the agents table (allow ANSI/box chars around it).
expect(status).toMatch(/Total\D+4/);
+ expect(status).toMatch(/Active\D+0/);
+ expect(status).toMatch(/Idle\D+4/);
+ const list = run(['agent', 'list'], wd).stdout;
+ expect(list).toMatch(/\| agent-\d+/);
// Sanity: the activity file the fix reads was actually written.
const activityPath = join(wd, '.claude-flow', 'metrics', 'swarm-activity.json');
if (existsSync(activityPath)) {
diff --git a/v3/@claude-flow/cli/__tests__/hooks-post-task-routing-dual-write-2786.test.ts b/v3/@claude-flow/cli/__tests__/hooks-post-task-routing-dual-write-2786.test.ts
index 541c20ad63..8ccefab9f3 100644
--- a/v3/@claude-flow/cli/__tests__/hooks-post-task-routing-dual-write-2786.test.ts
+++ b/v3/@claude-flow/cli/__tests__/hooks-post-task-routing-dual-write-2786.test.ts
@@ -83,6 +83,9 @@ describe('#2786 fix-2 β€” hooks_post-task JSON dual-write for metrics reader', (
expect(entry.metadata?.confidence).toBe(0.9);
// Namespace matches the AgentDB write (patterns) for parity.
expect(entry.namespace).toBe('patterns');
+ expect(bridgeRecordFeedback).toHaveBeenCalledWith(expect.objectContaining({
+ task: 'implement auth token refresh',
+ }));
});
it('does NOT write to store.json when storeDecisions is omitted (backwards compatible)', async () => {
diff --git a/v3/@claude-flow/cli/__tests__/integration-docker.test.ts b/v3/@claude-flow/cli/__tests__/integration-docker.test.ts
index 0cd8a2be8c..0d2a2bf1c0 100644
--- a/v3/@claude-flow/cli/__tests__/integration-docker.test.ts
+++ b/v3/@claude-flow/cli/__tests__/integration-docker.test.ts
@@ -89,8 +89,8 @@ describe('Docker Compose Configuration', () => {
expect(composeContent).toMatch(/image:\s*mongo:7/);
});
- it('mongodb exposes port 27017', () => {
- expect(composeContent).toMatch(/"27017:27017"/);
+ it('mongodb exposes port 27017 on loopback only', () => {
+ expect(composeContent).toMatch(/"127\.0\.0\.1:27017:27017"/);
});
it('mongodb has a named volume for data persistence', () => {
@@ -102,8 +102,8 @@ describe('Docker Compose Configuration', () => {
expect(composeContent).toMatch(/context:\s*\.\/src\/ruvocal\/mcp-bridge/);
});
- it('mcp-bridge publishes port 3001', () => {
- expect(composeContent).toMatch(/"3001:3001"/);
+ it('mcp-bridge publishes port 3001 on loopback only', () => {
+ expect(composeContent).toMatch(/"127\.0\.0\.1:3001:3001"/);
});
it('mcp-bridge has a healthcheck', () => {
@@ -145,7 +145,9 @@ describe('Docker Compose Configuration', () => {
it('chat-ui injects DOTENV_LOCAL with required env vars', () => {
expect(composeContent).toContain('DOTENV_LOCAL');
- expect(composeContent).toContain('MONGODB_URL=mongodb://mongodb:27017');
+ expect(composeContent).toMatch(
+ /MONGODB_URL=mongodb:\/\/\$\{MONGO_INITDB_ROOT_USERNAME[^}]*\}:\$\{MONGO_INITDB_ROOT_PASSWORD\}@mongodb:27017/,
+ );
expect(composeContent).toContain('PUBLIC_APP_NAME');
expect(composeContent).toContain('OPENAI_BASE_URL=http://mcp-bridge:3001');
});
@@ -385,8 +387,8 @@ describe('MCP Bridge Dockerfile', () => {
expect(existsSync(MCP_BRIDGE_DOCKERFILE)).toBe(true);
});
- it('uses Node.js 20 slim base image', () => {
- expect(dockerContent).toMatch(/FROM\s+node:20-slim/);
+ it('uses the supported Node.js 24 slim LTS base image', () => {
+ expect(dockerContent).toMatch(/FROM\s+node:24-slim/);
});
it('installs production dependencies', () => {
@@ -612,7 +614,7 @@ describe('Cross-Service Port Consistency', () => {
const dockerfile = readFile(MCP_BRIDGE_DOCKERFILE);
const compose = readFile(COMPOSE_PATH);
expect(dockerfile).toContain('EXPOSE 3001');
- expect(compose).toContain('"3001:3001"');
+ expect(compose).toContain('"127.0.0.1:3001:3001"');
});
it('nginx Dockerfile EXPOSE matches compose published port', () => {
diff --git a/v3/@claude-flow/cli/__tests__/issue-2805-embedding-backend-truth.test.ts b/v3/@claude-flow/cli/__tests__/issue-2805-embedding-backend-truth.test.ts
new file mode 100644
index 0000000000..6edf2531ee
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/issue-2805-embedding-backend-truth.test.ts
@@ -0,0 +1,52 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { tmpdir } from 'node:os';
+
+vi.mock('../src/memory/memory-initializer.js', () => ({
+ generateEmbedding: vi.fn(async (text: string) => ({
+ embedding: Array.from({ length: 8 }, (_, i) => Math.sin(text.length + i)),
+ dimensions: 8,
+ model: 'hash-fallback',
+ backend: 'mock',
+ })),
+ searchEntries: vi.fn(async () => ({ results: [] })),
+}));
+
+const { embeddingsTools } = await import('../src/mcp-tools/embeddings-tools.js');
+const init = embeddingsTools.find(tool => tool.name === 'embeddings_init')!;
+const status = embeddingsTools.find(tool => tool.name === 'embeddings_status')!;
+const compare = embeddingsTools.find(tool => tool.name === 'embeddings_compare')!;
+
+let originalCwd: string;
+let workdir: string;
+
+beforeEach(async () => {
+ originalCwd = process.cwd();
+ workdir = mkdtempSync(join(tmpdir(), 'ruflo-2805-'));
+ process.chdir(workdir);
+ await init.handler({ force: true });
+});
+
+afterEach(() => {
+ process.chdir(originalCwd);
+ rmSync(workdir, { recursive: true, force: true });
+});
+
+describe('#2805 embedding backend truthfulness', () => {
+ it('removes semantic-search claims while the hash fallback is active', async () => {
+ const result = await status.handler({}) as any;
+ expect(result.embeddingBackend).toBe('mock');
+ expect(result.semanticGrounded).toBe(false);
+ expect(result.capabilities.features).not.toContain('semantic search');
+ expect(result.warning).toMatch(/not semantically meaningful/i);
+ });
+
+ it('does not interpret hash similarity as semantic similarity', async () => {
+ const result = await compare.handler({ text1: 'a cat', text2: 'banking regulation' }) as any;
+ expect(result.embeddingBackend).toBe('mock');
+ expect(result.semanticGrounded).toBe(false);
+ expect(result.interpretation).toBeNull();
+ expect(result.warning).toMatch(/not semantically meaningful/i);
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/issue-2814-spinner-output.test.ts b/v3/@claude-flow/cli/__tests__/issue-2814-spinner-output.test.ts
new file mode 100644
index 0000000000..6b25f580d4
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/issue-2814-spinner-output.test.ts
@@ -0,0 +1,22 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { OutputFormatter } from '../../cli-core/src/output.js';
+
+describe('#2814 spinner output', () => {
+ afterEach(() => {
+ vi.restoreAllMocks();
+ });
+
+ it('emits no transient frames or clearing bytes when stdout is not a TTY', () => {
+ const isTTY = Object.getOwnPropertyDescriptor(process.stdout, 'isTTY');
+ Object.defineProperty(process.stdout, 'isTTY', { configurable: true, value: false });
+ const write = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+ try {
+ const spinner = new OutputFormatter({ color: false }).createSpinner({ text: 'Checking...' });
+ spinner.start();
+ spinner.stop();
+ expect(write).not.toHaveBeenCalled();
+ } finally {
+ if (isTTY) Object.defineProperty(process.stdout, 'isTTY', isTTY);
+ }
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/issue-2818-intelligence-project-root.test.ts b/v3/@claude-flow/cli/__tests__/issue-2818-intelligence-project-root.test.ts
new file mode 100644
index 0000000000..1cd589eb8e
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/issue-2818-intelligence-project-root.test.ts
@@ -0,0 +1,33 @@
+import { describe, expect, it } from 'vitest';
+import { execFileSync } from 'node:child_process';
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+
+const HELPER = resolve(__dirname, '../.claude/helpers/intelligence.cjs');
+
+describe('#2818 intelligence helper project-root storage', () => {
+ it('writes at CLAUDE_PROJECT_DIR and recovers legacy nested pending insights', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ruflo-2818-'));
+ const nested = join(root, 'src');
+ const legacyDir = join(nested, '.claude-flow', 'data');
+ mkdirSync(join(root, '.claude-flow'), { recursive: true });
+ mkdirSync(legacyDir, { recursive: true });
+ const legacyLine = JSON.stringify({ type: 'edit', file: 'legacy.ts', success: true });
+ writeFileSync(join(legacyDir, 'pending-insights.jsonl'), `${legacyLine}\n`, 'utf-8');
+
+ try {
+ execFileSync(process.execPath, ['-e', `require(${JSON.stringify(HELPER)}).recordEdit('current.ts', true)`], {
+ cwd: nested,
+ env: { ...process.env, CLAUDE_PROJECT_DIR: root },
+ });
+ const rootPending = join(root, '.claude-flow', 'data', 'pending-insights.jsonl');
+ expect(existsSync(rootPending)).toBe(true);
+ const contents = readFileSync(rootPending, 'utf-8');
+ expect(contents).toContain(legacyLine);
+ expect(contents).toContain('"file":"current.ts"');
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/mcp-tool-filter-2726.test.ts b/v3/@claude-flow/cli/__tests__/mcp-tool-filter-2726.test.ts
new file mode 100644
index 0000000000..8cbde51615
--- /dev/null
+++ b/v3/@claude-flow/cli/__tests__/mcp-tool-filter-2726.test.ts
@@ -0,0 +1,86 @@
+import { describe, expect, it } from 'vitest';
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import {
+ assessMcpSchemaOverhead,
+ filterAdvertisedMcpTools,
+ parseMcpToolSelection,
+} from '../src/mcp-server.js';
+
+const tools = [
+ {
+ name: 'memory_store',
+ category: 'memory',
+ description: 'Store persistent memory',
+ inputSchema: { type: 'object', properties: { value: { type: 'string' } } },
+ },
+ {
+ name: 'memory_search',
+ category: 'memory',
+ description: 'Search persistent memory',
+ inputSchema: { type: 'object', properties: { query: { type: 'string' } } },
+ },
+ {
+ name: 'swarm_init',
+ category: 'swarm',
+ description: 'Initialize a swarm',
+ inputSchema: { type: 'object', properties: { topology: { type: 'string' } } },
+ },
+ {
+ name: 'aidefence_scan',
+ category: 'security',
+ description: 'Scan untrusted content',
+ inputSchema: { type: 'object', properties: { text: { type: 'string' } } },
+ },
+];
+
+describe('MCP advertised-tool filtering (#2726)', () => {
+ it('keeps all schemas by default for backwards compatibility', () => {
+ expect(parseMcpToolSelection(undefined)).toBe('all');
+ expect(filterAdvertisedMcpTools(tools, 'all')).toEqual(tools);
+ });
+
+ it('accepts categories, namespace prefixes, and exact tool names', () => {
+ expect(filterAdvertisedMcpTools(tools, ['memory']).map((tool) => tool.name))
+ .toEqual(['memory_store', 'memory_search']);
+ expect(filterAdvertisedMcpTools(tools, ['security']).map((tool) => tool.name))
+ .toEqual(['aidefence_scan']);
+ expect(filterAdvertisedMcpTools(tools, ['swarm_init']).map((tool) => tool.name))
+ .toEqual(['swarm_init']);
+ });
+
+ it('materially reduces the fixed tools/list schema payload', () => {
+ const full = assessMcpSchemaOverhead(tools, 32_000);
+ const selected = filterAdvertisedMcpTools(tools, ['memory']);
+ const reduced = assessMcpSchemaOverhead(selected, 32_000);
+ expect(selected).toHaveLength(2);
+ expect(reduced.bytes).toBeLessThan(full.bytes);
+ expect(reduced.estimatedTokens).toBeLessThan(full.estimatedTokens);
+ });
+
+ it('flags catalogues consuming at least 20% of a configured context window', () => {
+ const oversized = Array.from({ length: 100 }, (_, index) => ({
+ name: `tool_${index}`,
+ description: 'x'.repeat(300),
+ inputSchema: { type: 'object', properties: { value: { type: 'string' } } },
+ }));
+ expect(assessMcpSchemaOverhead(oversized, 32_000)).toMatchObject({
+ toolCount: 100,
+ contextWindowTokens: 32_000,
+ risk: 'high',
+ });
+ });
+
+ it('parses CLAUDE_FLOW_MCP_TOOLS-compatible comma lists', () => {
+ expect(parseMcpToolSelection(' memory, swarm_init ,security '))
+ .toEqual(['memory', 'swarm_init', 'security']);
+ expect(parseMcpToolSelection(' ')).toBe('all');
+ });
+
+ it('applies filtering in the executable MCP fast path', () => {
+ const executable = readFileSync(join(process.cwd(), 'bin', 'cli.js'), 'utf8');
+ expect(executable).toContain('_filterAdvertisedMcpTools(listMCPTools())');
+ expect(executable).toContain('CLAUDE_FLOW_MCP_TOOLS');
+ expect(executable).toContain("arg === '--tools'");
+ });
+});
diff --git a/v3/@claude-flow/cli/__tests__/memory-distillation.test.ts b/v3/@claude-flow/cli/__tests__/memory-distillation.test.ts
index 85e89789b8..fbfb0d4c69 100644
--- a/v3/@claude-flow/cli/__tests__/memory-distillation.test.ts
+++ b/v3/@claude-flow/cli/__tests__/memory-distillation.test.ts
@@ -31,6 +31,11 @@ function seedDb(dbPath: string): void {
success BOOLEAN DEFAULT 0, latency_ms INTEGER, tokens_used INTEGER, tags TEXT,
metadata JSON, created_at INTEGER DEFAULT 0
)`);
+ db.exec(`CREATE TABLE episode_embeddings (
+ episode_id INTEGER PRIMARY KEY, embedding BLOB NOT NULL,
+ embedding_model TEXT DEFAULT 'all-MiniLM-L6-v2',
+ FOREIGN KEY(episode_id) REFERENCES episodes(id) ON DELETE CASCADE
+ )`);
db.exec(`CREATE TABLE reasoning_patterns (
id INTEGER PRIMARY KEY AUTOINCREMENT, ts INTEGER DEFAULT 0, task_type TEXT NOT NULL,
approach TEXT NOT NULL, success_rate REAL NOT NULL DEFAULT 0, uses INTEGER DEFAULT 0,
@@ -62,6 +67,7 @@ function counts(dbPath: string): Record<string, number> {
const q = (t: string) => (db.prepare(`SELECT COUNT(*) AS c FROM ${t}`).get() as { c: number }).c;
const r = {
memory_entries: q('memory_entries'), episodes: q('episodes'),
+ episode_embeddings: q('episode_embeddings'),
reasoning_patterns: q('reasoning_patterns'), pattern_embeddings: q('pattern_embeddings'),
causal_edges: q('causal_edges'),
};
@@ -89,8 +95,18 @@ describe.skipIf(!haveNative)('runDistillation β€” memory β†’ structured intellig
expect(after.memory_entries).toBe(before.memory_entries); // source untouched
expect(after.reasoning_patterns).toBeGreaterThan(0);
expect(after.episodes).toBeGreaterThan(0);
+ // ReflexionMemory uses an INNER JOIN, so episode coverage must be 1:1.
+ expect(after.episode_embeddings).toBe(after.episodes);
+ expect(r.episodeEmbeddings).toBe(r.episodes);
// Every pattern with a source embedding gets a pattern_embedding.
expect(after.pattern_embeddings).toBe(after.reasoning_patterns);
+
+ const check = new Database(dbPath, { readonly: true });
+ const feedbackWithCritique = (check.prepare(
+ "SELECT COUNT(*) AS c FROM episodes WHERE session_id='distill:feedback' AND length(trim(coalesce(critique,''))) > 0",
+ ).get() as { c: number }).c;
+ expect(feedbackWithCritique).toBeGreaterThan(0);
+ check.close();
});
it('enforces ADR-171 provenance: feedback promotes, proxy never does', async () => {
@@ -134,6 +150,42 @@ describe.skipIf(!haveNative)('runDistillation β€” memory β†’ structured intellig
expect(r.byProvenance['proxy:structural']).toBeUndefined();
});
+ it('migrates an older episodes-only store and makes distilled episodes retrievable', async () => {
+ const dbPath = join(workdir, 'legacy-reflexion.db');
+ seedDb(dbPath);
+ const before = new Database(dbPath);
+ before.prepare(
+ 'INSERT INTO episodes (session_id, task, input, metadata) VALUES (?,?,?,?)',
+ ).run(
+ 'distill:feedback',
+ 'legacy unembedded episode',
+ JSON.stringify({ taskId: 'legacy', success: false, error: 'old failure' }),
+ JSON.stringify({ sourceIds: ['f2'], provenance: 'oracle:test-exec' }),
+ );
+ before.exec('DROP TABLE episode_embeddings');
+ before.close();
+
+ const r = await runDistillation({ dbPath });
+ // Five new episodes plus the pre-existing legacy row are embedded.
+ expect(r.episodeEmbeddings).toBeGreaterThan(r.episodes);
+
+ const after = new Database(dbPath, { readonly: true });
+ const coverage = after.prepare(`
+ SELECT
+ (SELECT COUNT(*) FROM episodes) AS episodes,
+ (SELECT COUNT(*) FROM episode_embeddings) AS embeddings,
+ (SELECT COUNT(*) FROM episodes e
+ JOIN episode_embeddings ee ON ee.episode_id = e.id) AS retrievable
+ `).get() as { episodes: number; embeddings: number; retrievable: number };
+ expect(coverage.embeddings).toBe(coverage.episodes);
+ expect(coverage.retrievable).toBe(coverage.episodes);
+ const missingCritique = (after.prepare(
+ "SELECT COUNT(*) AS c FROM episodes WHERE session_id LIKE 'distill:feedback%' AND length(trim(coalesce(critique,'')))=0",
+ ).get() as { c: number }).c;
+ expect(missingCritique).toBe(0);
+ after.close();
+ });
+
it('skips (does not throw) when target tables are absent', async () => {
const dbPath = join(workdir, 'bare.db');
const db = new Database(dbPath);
diff --git a/v3/@claude-flow/cli/__tests__/statusline-cost-display.test.ts b/v3/@claude-flow/cli/__tests__/statusline-cost-display.test.ts
index 00a8c466ea..c31f11a2ef 100644
--- a/v3/@claude-flow/cli/__tests__/statusline-cost-display.test.ts
+++ b/v3/@claude-flow/cli/__tests__/statusline-cost-display.test.ts
@@ -108,7 +108,7 @@ describe('statusline cost display β€” committed artifact drift guard', () => {
it('matches the generator output for default options', () => {
const artifact = path.resolve(
path.dirname(fileURLToPath(import.meta.url)),
- '../../../../.claude/helpers/statusline.cjs',
+ '../.claude/helpers/statusline.cjs',
);
if (!existsSync(artifact)) return; // package tested in isolation; nothing to guard
// #2679 fix: generator now reads .claude/helpers/statusline.cjs as its
@@ -127,7 +127,9 @@ describe('statusline cost display β€” committed artifact drift guard', () => {
// environment can still see the two versions differ β€” that's not
// real drift, just resolution locale. Normalize before compare.
const normalizeVer = (s: string): string =>
- s.replace(/let ver = "[^"]+";/, 'let ver = "X.Y.Z";');
+ s
+ .replace(/let ver = "[^"]+";/, 'let ver = "X.Y.Z";')
+ .replace(/const BAKED_INSTALL_ROOT = "[^"]*";/, 'const BAKED_INSTALL_ROOT = "PACKAGE_ROOT";');
expect(normalizeVer(readFileSync(artifact, 'utf-8'))).toBe(normalizeVer(SCRIPT));
});
});
@@ -203,6 +205,11 @@ describe('getPkgVersion() β€” highest candidate wins, not first-found', () => {
expect(SCRIPT).toContain('compareVersions(pkg.version, ver) > 0');
});
+ it('includes the baked install root and common ~/.local npm prefix', () => {
+ expect(SCRIPT).toContain('const BAKED_INSTALL_ROOT = ');
+ expect(SCRIPT).toContain("path.join(home, '.local')");
+ });
+
it('renders the HIGHER of two real candidate package.json versions', () => {
const home = mkdtempSync(path.join(tmpdir(), 'ruflo-statusline-ver-home-'));
const cwd = mkdtempSync(path.join(tmpdir(), 'ruflo-statusline-ver-cwd-'));
diff --git a/v3/@claude-flow/cli/bin/cli.js b/v3/@claude-flow/cli/bin/cli.js
index 7991e152d7..d190e4d5dc 100755
--- a/v3/@claude-flow/cli/bin/cli.js
+++ b/v3/@claude-flow/cli/bin/cli.js
@@ -34,6 +34,30 @@ import { dirname, join } from 'path';
const _origWarn = console.warn;
const _origLog = console.log;
const _origError = console.error;
+
+// #2726 β€” Some MCP clients place every advertised schema in every model
+// request. Keep "all" as the backwards-compatible default, but honor the
+// same category/namespace/exact-name selector as `mcp start --tools`.
+function _filterAdvertisedMcpTools(tools) {
+ const argv = process.argv.slice(2);
+ const toolsIndex = argv.findIndex((arg) => arg === '--tools');
+ const inlineTools = argv.find((arg) => arg.startsWith('--tools='));
+ const configured = process.env.CLAUDE_FLOW_MCP_TOOLS
+ || (toolsIndex >= 0 ? argv[toolsIndex + 1] : undefined)
+ || (inlineTools ? inlineTools.slice('--tools='.length) : undefined);
+ if (!configured || configured.trim().toLowerCase() === 'all') return tools;
+ const selectors = new Set(
+ configured.split(',').map((item) => item.trim().toLowerCase()).filter(Boolean),
+ );
+ if (selectors.size === 0) return tools;
+ return tools.filter((tool) => {
+ const name = tool.name.toLowerCase();
+ const category = typeof tool.category === 'string' ? tool.category.toLowerCase() : '';
+ return selectors.has(name)
+ || selectors.has(category)
+ || Array.from(selectors).some((selector) => name.startsWith(`${selector}_`));
+ });
+}
const _isCosmeticAgentdbPatchNoise = (msg) =>
msg.includes('[AgentDB Patch]') && msg.includes('Controller index not found');
const _STDERR_REDIRECT_PREFIXES = [
@@ -237,7 +261,7 @@ if (isMCPMode) {
};
case 'tools/list': {
- const tools = listMCPTools();
+ const tools = _filterAdvertisedMcpTools(listMCPTools());
return {
jsonrpc: '2.0',
id: message.id,
diff --git a/v3/@claude-flow/cli/catalog-manifest.json b/v3/@claude-flow/cli/catalog-manifest.json
index 12b4c94cb5..7f367b825f 100644
--- a/v3/@claude-flow/cli/catalog-manifest.json
+++ b/v3/@claude-flow/cli/catalog-manifest.json
@@ -1,8 +1,8 @@
{
"schemaVersion": 1,
"generation": 4,
- "generatedAt": "2026-07-29T17:53:37.877Z",
- "gitSha": "9cf769cc",
+ "generatedAt": "2026-07-29T18:44:50.000Z",
+ "gitSha": "f98fc42c",
"catalog": {
"agents": 164,
"tools": 397,
diff --git a/v3/@claude-flow/cli/package.json b/v3/@claude-flow/cli/package.json
index 7acf644795..7477b8254c 100644
--- a/v3/@claude-flow/cli/package.json
+++ b/v3/@claude-flow/cli/package.json
@@ -1,6 +1,6 @@
{
"name": "@claude-flow/cli",
- "version": "3.32.35",
+ "version": "3.32.36",
"type": "module",
"description": "Ruflo CLI - Enterprise AI agent orchestration with 60+ specialized agents, swarm coordination, MCP server, self-learning hooks, and vector memory for Claude Code",
"main": "dist/src/index.js",
diff --git a/v3/@claude-flow/cli/scripts/sign-helpers.mjs b/v3/@claude-flow/cli/scripts/sign-helpers.mjs
index eb1e085909..a416cf321d 100644
--- a/v3/@claude-flow/cli/scripts/sign-helpers.mjs
+++ b/v3/@claude-flow/cli/scripts/sign-helpers.mjs
@@ -15,10 +15,13 @@
* 2. RUFLO_HELPERS_SIGNING_KEY=<pem-file-path> (local / air-gapped)
* 3. ~/.ruflo/helpers-signing.key (dev default)
*
+ * Stdin fallback (the PEM never appears in shell output or argv):
+ * gcloud secrets versions access latest --secret=... | node scripts/sign-helpers.mjs --stdin-key
+ *
* Usage: RUFLO_HELPERS_SIGNING_SECRET=ruflo-helpers-signing-key node scripts/sign-helpers.mjs
*/
import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-import { createHash, sign as edSign } from 'node:crypto';
+import { createHash, createPrivateKey, sign as edSign } from 'node:crypto';
import { execFileSync } from 'node:child_process';
import { join, dirname } from 'node:path';
import { fileURLToPath } from 'node:url';
@@ -31,19 +34,36 @@ const HELPERS_DIR = join(PKG_ROOT, '.claude', 'helpers');
const CRITICAL = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs'];
function loadPrivateKey() {
+ if (process.argv.includes('--stdin-key')) {
+ if (process.stdin.isTTY) {
+ console.error(
+ '[sign-helpers] --stdin-key requires piped stdin; refusing interactive key entry. ' +
+ 'Pipe Secret Manager output directly or use RUFLO_HELPERS_SIGNING_KEY=<pem-file-path>.',
+ );
+ process.exit(1);
+ }
+ const key = readFileSync(0, 'utf-8');
+ if (!key.trim()) {
+ console.error('[sign-helpers] --stdin-key received empty input');
+ process.exit(1);
+ }
+ return key;
+ }
+
const secret = process.env.RUFLO_HELPERS_SIGNING_SECRET;
if (secret) {
const args = ['secrets', 'versions', 'access', 'latest', '--secret', secret];
const project = process.env.RUFLO_HELPERS_SIGNING_PROJECT;
if (project) args.push('--project', project);
try {
+ const gcloudBin = process.platform === 'win32' ? 'gcloud.cmd' : 'gcloud';
// stdio: key on stdout (captured), stderr captured too β€” NOT inherited.
// Inheriting would forward gcloud's stderr verbatim into whatever log
// is capturing this process's output (CI, terminal); this key material
// is sensitive enough that we never want an uncontrolled passthrough,
// even though gcloud's normal error paths don't echo secret payloads.
- return execFileSync('gcloud', args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
- } catch (e) {
+ return execFileSync(gcloudBin, args, { encoding: 'utf-8', stdio: ['ignore', 'pipe', 'pipe'] });
+ } catch {
console.error(`[sign-helpers] failed to read GCP secret '${secret}'. Is gcloud authed? (gcloud auth login)`);
process.exit(1);
}
@@ -60,6 +80,14 @@ function loadPrivateKey() {
}
const privateKeyPem = loadPrivateKey();
+try {
+ const key = createPrivateKey(privateKeyPem);
+ if (key.asymmetricKeyType !== 'ed25519') throw new Error('wrong-key-type');
+} catch {
+ // Never include the PEM or the crypto parser's input in diagnostics.
+ console.error('[sign-helpers] signing key is not a valid Ed25519 private key');
+ process.exit(1);
+}
const version = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf-8')).version;
const files = {};
diff --git a/v3/@claude-flow/cli/scripts/verify-helpers.mjs b/v3/@claude-flow/cli/scripts/verify-helpers.mjs
index f933c37c05..c78cc08dd1 100644
--- a/v3/@claude-flow/cli/scripts/verify-helpers.mjs
+++ b/v3/@claude-flow/cli/scripts/verify-helpers.mjs
@@ -24,15 +24,18 @@ const HELPERS_DIR = resolve(process.argv[2] || join(PKG_ROOT, '.claude', 'helper
// Keep in sync with sign-helpers.mjs:CRITICAL and src/init/helper-refresh.ts:CRITICAL_HELPERS.
const CRITICAL = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'statusline.cjs'];
-// KEEP IN SYNC with src/init/helper-signing.ts:RUFLO_HELPERS_PUBKEY.
-// Rotated 2026-07-14 (v3.29.0) after the previous private key was exposed in
-// a Claude Code session transcript. Old GCP secret v1 destroyed.
-const RUFLO_HELPERS_PUBKEY = `-----BEGIN PUBLIC KEY-----
-MCowBQYDK2VwAyEAyLl9cG+V/C+ffKWaSwvOsHdXSWmB5e3x1z9NUNvq6Ys=
------END PUBLIC KEY-----`;
-
function die(msg) { console.error(`[verify-helpers] ${msg}`); process.exit(1); }
+// #2675 β€” helper-signing.ts is the sole key source. prepare-publish.mjs and
+// stable-npm-release.yml both build before verification, so importing emitted
+// runtime code preserves the exact key users will trust after installation.
+let RUFLO_HELPERS_PUBKEY;
+try {
+ ({ RUFLO_HELPERS_PUBKEY } = await import('../dist/src/init/helper-signing.js'));
+} catch {
+ die('compiled helper-signing.js is unavailable; run `npm run build` before verification');
+}
+
const manifestPath = join(HELPERS_DIR, 'helpers.manifest.json');
if (!existsSync(manifestPath)) die(`missing manifest: ${manifestPath}`);
diff --git a/v3/@claude-flow/cli/src/commands/agent.ts b/v3/@claude-flow/cli/src/commands/agent.ts
index 118a9533db..eb1352e138 100644
--- a/v3/@claude-flow/cli/src/commands/agent.ts
+++ b/v3/@claude-flow/cli/src/commands/agent.ts
@@ -236,9 +236,9 @@ const listCommand: Command = {
// Call MCP tool to list agents
const result = await callMCPTool<{
agents: Array<{
- id: string;
+ agentId: string;
agentType: string;
- status: 'active' | 'idle' | 'terminated';
+ status: 'active' | 'busy' | 'idle' | 'terminated';
createdAt: string;
lastActivityAt?: string;
}>;
@@ -265,7 +265,7 @@ const listCommand: Command = {
// Format for display
const displayAgents = result.agents.map(agent => ({
- id: agent.id,
+ id: agent.agentId,
type: agent.agentType,
status: agent.status,
created: new Date(agent.createdAt).toLocaleTimeString(),
diff --git a/v3/@claude-flow/cli/src/commands/doctor.ts b/v3/@claude-flow/cli/src/commands/doctor.ts
index d9036f0932..d4aef22764 100644
--- a/v3/@claude-flow/cli/src/commands/doctor.ts
+++ b/v3/@claude-flow/cli/src/commands/doctor.ts
@@ -139,8 +139,8 @@ async function checkConfigFile(): Promise<HealthCheck> {
// Check daemon status
/**
- * #2448 β€” Detect the runaway `npx @claude-flow/cli@latest` statusLine / hook
- * commands left over in `.claude/settings.json` from pre-#2337 installs.
+ * #2448 / #2677 β€” Detect runaway `npx @claude-flow/cli@latest` commands
+ * left over in `.claude/settings.json` from pre-#2337 installs.
*
* These fire on every Claude Code event (statusLine refires every few hundred
* ms, hooks fire per tool-use), each spawning a cold Node process + npm
@@ -157,7 +157,9 @@ async function checkStaleSettingsNpx(): Promise<HealthCheck> {
// 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+)/;
+ // Every subcommand incurs the same cold npm process/registry cost. The
+ // previous `hooks` literal missed `memory`, `daemon`, `swarm`, etc.
+ const BROKEN_RE = /npx\s+(?:--?\S+\s+){0,10}@?claude-flow\/cli@latest\s+\S+/;
// Look in both project-local and home-dir settings.
const candidates = [
@@ -290,18 +292,21 @@ async function checkMemoryDatabase(): Promise<HealthCheck> {
// The existing `checkMemoryDatabase` above asserts existence + statability
// only, so it CANNOT distinguish a healthy DB from a 99.97%-empty or
// SQLite-malformed one. Stuinfla reported both cases live (81-store fleet).
-// The three checks below layer functional assertions on top, ordered so
+// The checks below layer functional assertions on top, ordered so
// the earliest chain-break is always the first red the user sees:
// 1. Integrity β€” can sql.js open it AND does PRAGMA integrity_check pass?
// 2. Content β€” do most memory_entries rows carry non-empty content?
// 3. Embedding coverage β€” do most rows have a vector? (unembedded rows are
// both unrecallable AND undistillable per ADR-174)
+// 6. Reflexion coverage β€” can episodes participate in retrieveRelevant's
+// required episode_embeddings INNER JOIN?
+// Feedback critiques β€” do execution-tier episodes carry a real lesson?
// Ordering matters: content ratio is meaningless on a DB that can't open;
// embedding coverage is meaningless on rows with no content. First red wins.
//
-// Recall probe (stuinfla check 4) requires actual write+search+delete round
-// trips through the CLI's own memory pipeline β€” deferred to a follow-up PR
-// to keep this one purely additive and safe.
+// Recall probe (stuinfla check 4) still requires an isolated write+search+
+// delete round trip through the CLI's own memory pipeline. It remains separate
+// because doctor otherwise stays read-only.
//
// Design rules (also from stuinfla's report):
// - "A check that cannot fail protects nothing" β€” every check has a
@@ -722,6 +727,92 @@ async function checkMemoryEmbeddingCoverage(): Promise<HealthCheck> {
} finally { try { db.close(); } catch { /* best-effort */ } }
}
+// #2677 check 6 β€” ReflexionMemory.retrieveRelevant() INNER JOINs episodes to
+// episode_embeddings. A populated episodes table with an empty/missing partner
+// table is therefore not degraded recall; it is structurally zero recall.
+async function checkMemoryReflexionCoverage(): Promise<HealthCheck> {
+ const dbPath = await resolveMemoryDbPath();
+ if (!dbPath) return { name: 'Memory Reflexion Coverage', status: 'warn', message: 'no memory.db found' };
+ const db = await tryOpenSqlJs(dbPath);
+ if (!db) return { name: 'Memory Reflexion Coverage', status: 'warn', message: 'DB unreadable (see Memory Integrity)' };
+ try {
+ const tables = new Set<string>(
+ db.exec("SELECT name FROM sqlite_master WHERE type='table' AND name IN ('episodes','episode_embeddings')")
+ [0]?.values?.map((v: any[]) => String(v[0])) ?? [],
+ );
+ if (!tables.has('episodes')) {
+ return { name: 'Memory Reflexion Coverage', status: 'warn', message: 'episodes table absent β€” AgentDB Reflexion schema not initialized' };
+ }
+ const episodes = Number(db.exec('SELECT count(*) FROM episodes')[0]?.values?.[0]?.[0] ?? 0);
+ if (episodes === 0) {
+ return { name: 'Memory Reflexion Coverage', status: 'warn', message: `${dbPath} β€” 0 episodes (Reflexion has not been exercised)` };
+ }
+ if (!tables.has('episode_embeddings')) {
+ return {
+ name: 'Memory Reflexion Coverage',
+ status: 'fail',
+ message: `${dbPath} β€” episode embeddings 0/${episodes} (0.00%); retrieveRelevant() cannot return rows`,
+ fix: 'run `claude-flow memory distill run`; current distillation creates/backfills episode_embeddings',
+ };
+ }
+ const embedded = Number(db.exec(
+ 'SELECT count(*) FROM episodes e JOIN episode_embeddings ee ON ee.episode_id=e.id',
+ )[0]?.values?.[0]?.[0] ?? 0);
+ const ratio = embedded / episodes;
+ const detail = `episode embeddings ${embedded}/${episodes} (${(ratio * 100).toFixed(2)}%)`;
+ if (ratio < 0.95) {
+ return {
+ name: 'Memory Reflexion Coverage',
+ status: 'fail',
+ message: `${dbPath} β€” ${detail} below 95% floor; retrieveRelevant() cannot see uncovered episodes`,
+ fix: 'run `claude-flow memory distill run` to populate retrievable episodes',
+ };
+ }
+ return { name: 'Memory Reflexion Coverage', status: 'pass', message: `${dbPath} β€” ${detail}` };
+ } catch (e) {
+ return { name: 'Memory Reflexion Coverage', status: 'warn', message: `${dbPath} β€” probe threw: ${(e as Error).message || String(e)}` };
+ } finally { try { db.close(); } catch { /* best-effort */ } }
+}
+
+// Execution-tier feedback should carry a lesson, not just reward/success bits.
+// Proxy episodes intentionally remain critique-free to avoid laundering a
+// structural summary into an observed failure explanation.
+async function checkMemoryCritiqueCoverage(): Promise<HealthCheck> {
+ const dbPath = await resolveMemoryDbPath();
+ if (!dbPath) return { name: 'Memory Feedback Critiques', status: 'warn', message: 'no memory.db found' };
+ const db = await tryOpenSqlJs(dbPath);
+ if (!db) return { name: 'Memory Feedback Critiques', status: 'warn', message: 'DB unreadable (see Memory Integrity)' };
+ try {
+ const hasEpisodes = (db.exec(
+ "SELECT count(*) FROM sqlite_master WHERE type='table' AND name='episodes'",
+ )[0]?.values?.[0]?.[0] ?? 0) > 0;
+ if (!hasEpisodes) return { name: 'Memory Feedback Critiques', status: 'warn', message: 'episodes table absent' };
+ const row = db.exec(`
+ SELECT count(*),
+ sum(CASE WHEN length(trim(coalesce(critique,''))) > 0 THEN 1 ELSE 0 END)
+ FROM episodes WHERE session_id LIKE 'distill:feedback%'
+ `)[0]?.values?.[0] ?? [0, 0];
+ const feedback = Number(row[0] ?? 0);
+ const withCritique = Number(row[1] ?? 0);
+ if (feedback === 0) {
+ return { name: 'Memory Feedback Critiques', status: 'warn', message: `${dbPath} β€” 0 execution-feedback episodes to assess` };
+ }
+ const ratio = withCritique / feedback;
+ const detail = `feedback critiques ${withCritique}/${feedback} (${(ratio * 100).toFixed(2)}%)`;
+ if (ratio < 0.95) {
+ return {
+ name: 'Memory Feedback Critiques',
+ status: 'fail',
+ message: `${dbPath} β€” ${detail} below 95% floor`,
+ fix: 'run current `claude-flow memory distill run`; execution-tier episodes preserve observed critique/error text',
+ };
+ }
+ return { name: 'Memory Feedback Critiques', status: 'pass', message: `${dbPath} β€” ${detail}` };
+ } catch (e) {
+ return { name: 'Memory Feedback Critiques', status: 'warn', message: `${dbPath} β€” probe threw: ${(e as Error).message || String(e)}` };
+ } finally { try { db.close(); } catch { /* best-effort */ } }
+}
+
// #2545: Check that the self-learning bridge can actually load @claude-flow/memory
// the SAME way the SessionStart auto-memory hook does. On the documented `npx ruflo`
// path the package lands in the npx cache β€” unreachable from the project β€” so the
@@ -1037,6 +1128,53 @@ async function checkMcpServers(): Promise<HealthCheck> {
};
}
+// #2726 β€” tools/list is fixed prompt overhead on clients/backends that do not
+// defer MCP schemas. Measure the actual live registry and warn before a small
+// context window becomes unrecoverable even after compaction.
+async function checkMcpSchemaOverhead(): Promise<HealthCheck> {
+ try {
+ const [{ listMCPTools }, {
+ assessMcpSchemaOverhead,
+ filterAdvertisedMcpTools,
+ parseMcpToolSelection,
+ }] = await Promise.all([
+ import('../mcp-client.js'),
+ import('../mcp-server.js'),
+ ]);
+ // The `mcp start --tools` CLI flag takes precedence when the server is
+ // constructed. Doctor intentionally inspects the environment fallback so
+ // its estimate describes the configuration inherited by MCP clients.
+ const selection = parseMcpToolSelection(process.env.CLAUDE_FLOW_MCP_TOOLS);
+ const tools = filterAdvertisedMcpTools(listMCPTools(), selection);
+ // This is diagnostic metadata about the external client's context window,
+ // not Ruflo command configuration, so there is no corresponding CLI flag.
+ const rawWindow = process.env.CLAUDE_FLOW_CONTEXT_WINDOW_TOKENS;
+ const contextWindow = rawWindow ? Number.parseInt(rawWindow, 10) : undefined;
+ const assessment = assessMcpSchemaOverhead(tools, contextWindow);
+ const ratio = assessment.ratio === undefined
+ ? ''
+ : `, ${(assessment.ratio * 100).toFixed(1)}% of ${assessment.contextWindowTokens}-token window`;
+ const selectionLabel = selection === 'all' ? 'all tools' : `filtered: ${selection.join(',')}`;
+ const message = `${assessment.toolCount} advertised tools β‰ˆ ${assessment.estimatedTokens} schema tokens (${selectionLabel}${ratio})`;
+
+ if (assessment.risk === 'high') {
+ return {
+ name: 'MCP Schema Overhead',
+ status: 'warn',
+ message,
+ fix: 'Set CLAUDE_FLOW_MCP_TOOLS to required categories/tool names (for example: memory,swarm,agent,hooks) and optionally CLAUDE_FLOW_CONTEXT_WINDOW_TOKENS to your backend limit.',
+ };
+ }
+ return { name: 'MCP Schema Overhead', status: 'pass', message };
+ } catch (error) {
+ return {
+ name: 'MCP Schema Overhead',
+ status: 'warn',
+ message: `Unable to measure: ${error instanceof Error ? error.message : String(error)}`,
+ };
+ }
+}
+
// Check disk space (async with proper env inheritance)
async function checkDiskSpace(): Promise<HealthCheck> {
try {
@@ -1887,7 +2025,7 @@ export const doctorCommand: Command = {
{
name: 'component',
short: 'c',
- description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, claude, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, auth, metaharness)',
+ description: 'Check specific component (version, node, npm, config, daemon, memory, api, git, mcp, mcp-overhead, claude, disk, typescript, agentic-flow, encryption, federation, funnel, proxy, auth, metaharness)',
type: 'string'
},
{
@@ -2010,13 +2148,14 @@ export const doctorCommand: Command = {
checkGit,
checkGitRepo,
checkConfigFile,
- checkStaleSettingsNpx, // #2448 β€” runaway `npx @latest` in statusLine/hooks
+ checkStaleSettingsNpx, // #2448/#2677 β€” runaway `npx @latest` in settings
checkDaemonStatus,
checkMemoryDatabase,
checkMemoryStructuralIntegrity, // #2737 β€” bounded, native quick_check on every default run
checkLearningBridge, // #2545 β€” can the auto-memory hook actually load @claude-flow/memory?
checkApiKeys,
checkMcpServers,
+ checkMcpSchemaOverhead, // #2726 β€” fixed tools/list prompt cost
checkAIDefence, // #1807
checkDiskSpace,
checkBuildTools,
@@ -2035,8 +2174,9 @@ export const doctorCommand: Command = {
// array β€” expanded at execution time. Stuinfla's report showed the
// existence-only check reporting PASS on a 99.97%-empty and even a
// SQLite-malformed DB; the array here layers integrity β†’ content β†’
- // embedding coverage over the existing existence probe, ordered so
- // the earliest chain-break is always the first red the user sees.
+ // embedding coverage over the existing existence probe; check 6 then
+ // verifies that distilled episodes are actually Reflexion-retrievable and
+ // execution feedback carries a lesson.
const componentMap: Record<string, (() => Promise<HealthCheck>) | Array<() => Promise<HealthCheck>>> = {
'version': checkVersionFreshness,
'freshness': checkVersionFreshness,
@@ -2051,12 +2191,15 @@ export const doctorCommand: Command = {
checkMemoryIntegrity, // #2677 check 1: sql.js open + PRAGMA integrity_check
checkMemoryContent, // #2677 check 2: memory_entries content coverage
checkMemoryEmbeddingCoverage, // #2677 check 3: vector coverage on populated rows
+ checkMemoryReflexionCoverage, // #2677 check 6: episodes are retrievable
+ checkMemoryCritiqueCoverage, // #2677 check 6: feedback carries lessons
],
'learning': checkLearningBridge, // #2545
'learning-bridge': checkLearningBridge, // #2545
'api': checkApiKeys,
'git': checkGit,
'mcp': checkMcpServers,
+ 'mcp-overhead': checkMcpSchemaOverhead,
'aidefence': checkAIDefence, // #1807
'disk': checkDiskSpace,
'typescript': checkBuildTools,
diff --git a/v3/@claude-flow/cli/src/commands/hooks.ts b/v3/@claude-flow/cli/src/commands/hooks.ts
index 2bb163006a..1ec82f23e3 100644
--- a/v3/@claude-flow/cli/src/commands/hooks.ts
+++ b/v3/@claude-flow/cli/src/commands/hooks.ts
@@ -1486,6 +1486,9 @@ const metricsCommand: Command = {
total?: number;
successful?: number;
failed?: number;
+ unknown?: number;
+ described?: number;
+ descriptionCoverage?: number;
avgConfidence?: number;
};
routing?: {
@@ -1495,6 +1498,8 @@ const metricsCommand: Command = {
};
agents?: {
routingAccuracy?: number;
+ averageConfidence?: number;
+ outcomeSuccessRate?: number;
totalRoutes?: number;
topAgent?: string;
};
@@ -1524,9 +1529,25 @@ const metricsCommand: Command = {
const totalPatterns = safeNum(rawMetrics.patterns?.total ?? rawMetrics.summary?.patternsLearned);
const successfulPatterns = safeNum(rawMetrics.patterns?.successful ?? Math.round(safeNum(rawMetrics.summary?.successRate) * totalPatterns));
const failedPatterns = Math.max(0, safeNum(rawMetrics.patterns?.failed ?? totalPatterns - successfulPatterns));
+ const unknownPatterns = Math.max(0, safeNum(rawMetrics.patterns?.unknown));
+ const describedPatterns = Math.max(0, safeNum(rawMetrics.patterns?.described));
+ const descriptionCoverage = safeNum(
+ rawMetrics.patterns?.descriptionCoverage ??
+ (totalPatterns > 0 ? describedPatterns / totalPatterns : 0),
+ );
const avgConfidence = safeNum(rawMetrics.patterns?.avgConfidence ?? rawMetrics.summary?.avgQuality);
- const routingAccuracy = safeNum(rawMetrics.agents?.routingAccuracy ?? rawMetrics.routing?.avgConfidence);
+ const routingAccuracy = rawMetrics.agents?.routingAccuracy == null
+ ? null
+ : safeNum(rawMetrics.agents.routingAccuracy);
+ const averageRoutingConfidence = safeNum(
+ rawMetrics.agents?.averageConfidence ??
+ rawMetrics.routing?.avgConfidence ??
+ rawMetrics.patterns?.avgConfidence,
+ );
+ const routingOutcomeSuccessRate = rawMetrics.agents?.outcomeSuccessRate == null
+ ? null
+ : safeNum(rawMetrics.agents.outcomeSuccessRate);
const totalRoutes = safeNum(rawMetrics.agents?.totalRoutes ?? rawMetrics.routing?.totalRoutes);
const topAgent = rawMetrics.agents?.topAgent ?? rawMetrics.routing?.topAgents?.[0]?.agent ?? 'n/a';
@@ -1536,8 +1557,22 @@ const metricsCommand: Command = {
const result = {
...rawMetrics,
- patterns: { total: totalPatterns, successful: successfulPatterns, failed: failedPatterns, avgConfidence },
- agents: { routingAccuracy, totalRoutes, topAgent },
+ patterns: {
+ total: totalPatterns,
+ successful: successfulPatterns,
+ failed: failedPatterns,
+ unknown: unknownPatterns,
+ described: describedPatterns,
+ descriptionCoverage,
+ avgConfidence,
+ },
+ agents: {
+ routingAccuracy,
+ averageConfidence: averageRoutingConfidence,
+ outcomeSuccessRate: routingOutcomeSuccessRate,
+ totalRoutes,
+ topAgent,
+ },
commands: { totalExecuted: totalCommands, successRate: commandSuccessRate, avgRiskScore },
};
@@ -1557,6 +1592,8 @@ const metricsCommand: Command = {
{ metric: 'Total Patterns', value: totalPatterns },
{ metric: 'Successful', value: output.success(String(successfulPatterns)) },
{ metric: 'Failed', value: output.error(String(failedPatterns)) },
+ ...(unknownPatterns > 0 ? [{ metric: 'Unclassified', value: String(unknownPatterns) }] : []),
+ { metric: 'With Task Context', value: `${(descriptionCoverage * 100).toFixed(1)}%` },
{ metric: 'Avg Confidence', value: `${(avgConfidence * 100).toFixed(1)}%` }
]
});
@@ -1571,7 +1608,14 @@ const metricsCommand: Command = {
{ key: 'value', header: 'Value', width: 20, align: 'right' }
],
data: [
- { metric: 'Routing Accuracy', value: `${(routingAccuracy * 100).toFixed(1)}%` },
+ {
+ metric: routingAccuracy === null ? 'Avg Confidence' : 'Routing Accuracy',
+ value: `${((routingAccuracy ?? averageRoutingConfidence) * 100).toFixed(1)}%`,
+ },
+ ...(routingOutcomeSuccessRate === null ? [] : [{
+ metric: 'Outcome Success Rate',
+ value: `${(routingOutcomeSuccessRate * 100).toFixed(1)}%`,
+ }]),
{ metric: 'Total Routes', value: totalRoutes },
{ metric: 'Top Agent', value: output.highlight(topAgent) }
]
diff --git a/v3/@claude-flow/cli/src/commands/mcp.ts b/v3/@claude-flow/cli/src/commands/mcp.ts
index 8f11b12763..6333f0f475 100644
--- a/v3/@claude-flow/cli/src/commands/mcp.ts
+++ b/v3/@claude-flow/cli/src/commands/mcp.ts
@@ -77,7 +77,7 @@ const startCommand: Command = {
},
{
name: 'tools',
- description: 'Tools to enable (comma-separated or "all")',
+ description: 'Tools to advertise (comma-separated categories, prefixes, exact names, or "all")',
type: 'string',
default: 'all'
},
diff --git a/v3/@claude-flow/cli/src/commands/memory-distill.ts b/v3/@claude-flow/cli/src/commands/memory-distill.ts
index 787a2d0315..49430ac78c 100644
--- a/v3/@claude-flow/cli/src/commands/memory-distill.ts
+++ b/v3/@claude-flow/cli/src/commands/memory-distill.ts
@@ -217,6 +217,7 @@ const runCommand: Command = {
data: [
{ metric: 'Processed', value: String(report.processed) },
{ metric: 'Episodes', value: String(report.episodes) },
+ { metric: 'Episode Embeddings', value: String(report.episodeEmbeddings) },
{ metric: 'Patterns', value: String(report.patterns) },
{ metric: 'Pattern Embeddings', value: String(report.patternEmbeddings) },
{ metric: 'Causal Edges', value: String(report.causalEdges) },
diff --git a/v3/@claude-flow/cli/src/commands/swarm.ts b/v3/@claude-flow/cli/src/commands/swarm.ts
index 9123e2274b..3c51a9dd5c 100644
--- a/v3/@claude-flow/cli/src/commands/swarm.ts
+++ b/v3/@claude-flow/cli/src/commands/swarm.ts
@@ -54,6 +54,35 @@ function getSwarmStatus(swarmId?: string) {
}
}
+ // The canonical agent registry is the same source used by `agent list`.
+ // Prefer it over the swarm-level coordination boolean so idle agents are
+ // not reported as active (#2808). Hive agents are merged additively.
+ if (totalAgents === 0) {
+ try {
+ const canonicalPath = path.join(process.cwd(), '.claude-flow', 'agents', 'store.json');
+ const hivePath = path.join(process.cwd(), '.claude-flow', 'agents.json');
+ const merged: Record<string, { status?: string }> = {};
+ for (const storePath of [hivePath, canonicalPath]) {
+ if (!fs.existsSync(storePath)) continue;
+ const parsed = JSON.parse(fs.readFileSync(storePath, 'utf-8'));
+ if (parsed?.agents && typeof parsed.agents === 'object') {
+ Object.assign(merged, parsed.agents);
+ }
+ }
+ const agents = Object.values(merged).filter(agent => agent.status !== 'terminated');
+ if (agents.length > 0) {
+ totalAgents = agents.length;
+ activeAgents = agents.filter(agent =>
+ agent.status === 'active' ||
+ agent.status === 'running' ||
+ agent.status === 'busy'
+ ).length;
+ }
+ } catch {
+ // Ignore β€” the count-only activity file remains the final fallback.
+ }
+ }
+
// #2799 β€” `agent spawn` never writes `.swarm/agents/*.json`; it records
// the count in `.claude-flow/metrics/swarm-activity.json` (via
// updateSwarmActivityMetrics in commands/agent.ts). So when the agents
diff --git a/v3/@claude-flow/cli/src/init/executor.ts b/v3/@claude-flow/cli/src/init/executor.ts
index 9daa2c13e9..4f58ca43ea 100644
--- a/v3/@claude-flow/cli/src/init/executor.ts
+++ b/v3/@claude-flow/cli/src/init/executor.ts
@@ -430,10 +430,11 @@ function mergeSettingsForUpgrade(existing: Record<string, unknown>): Record<stri
// js/redos): a crafted settings.json command string with dozens of
// dash-token repetitions can hang this check for minutes.
const BROKEN_STATUSLINE_RE = /(?:npx\s+(?:--?\S+\s+){0,10})?@?claude-flow(?:\/cli)?(?:@\S+)?\s+hooks\s+statusline/;
+ const BROKEN_NPX_LATEST_RE = /npx\s+(?:--?\S+\s+){0,10}@?claude-flow\/cli@latest\s+\S+/;
const existingStatusLine = existing.statusLine as Record<string, unknown> | undefined;
if (existingStatusLine) {
const existingCmd = typeof existingStatusLine.command === 'string' ? existingStatusLine.command : '';
- const isBroken = BROKEN_STATUSLINE_RE.test(existingCmd);
+ const isBroken = BROKEN_STATUSLINE_RE.test(existingCmd) || BROKEN_NPX_LATEST_RE.test(existingCmd);
merged.statusLine = {
type: 'command',
command: isBroken || !existingCmd ? NEW_STATUSLINE_CMD : existingCmd,
@@ -441,8 +442,8 @@ function mergeSettingsForUpgrade(existing: Record<string, unknown>): Record<stri
};
}
- // #2448 β€” Detect and REGENERATE per-action hook commands that still use
- // the runaway `npx @claude-flow/cli@latest hooks <sub>` form. These fire
+ // #2448 / #2677 β€” Detect and REGENERATE per-action hook commands that still
+ // use the runaway `npx @claude-flow/cli@latest hooks <sub>` form. These fire
// on every PreToolUse/PostToolUse/UserPromptSubmit, each spawning ~130 MB
// of cold Node + npm registry resolution; the storm is what kernel-paniced
// the reporter's machine in #2448.
@@ -468,13 +469,19 @@ function mergeSettingsForUpgrade(existing: Record<string, unknown>): Record<stri
if (!Array.isArray(groups)) continue;
for (const group of groups) {
if (!Array.isArray(group.hooks)) continue;
- for (const h of group.hooks) {
- if (typeof h?.command !== 'string') continue;
+ group.hooks = group.hooks.filter((h) => {
+ if (typeof h?.command !== 'string') return true;
const m = BROKEN_HOOK_RE.exec(h.command);
- if (!m) continue;
- // Subcommand captured (e.g. "pre-bash", "post-edit", "route") β€” keep it.
- h.command = localHookCmd(m[1]);
- }
+ if (m) {
+ // Subcommand captured (e.g. "pre-bash", "post-edit", "route") β€” keep it.
+ h.command = localHookCmd(m[1]);
+ return true;
+ }
+ // Sibling CLI invocations (memory/daemon/swarm/...) have no
+ // hook-handler equivalent. Drop the stale extra; the merge above
+ // has already installed current local-helper hooks for this event.
+ return !BROKEN_NPX_LATEST_RE.test(h.command);
+ });
}
}
}
diff --git a/v3/@claude-flow/cli/src/init/helpers-generator.ts b/v3/@claude-flow/cli/src/init/helpers-generator.ts
index 7e664702c2..0b462bba5b 100644
--- a/v3/@claude-flow/cli/src/init/helpers-generator.ts
+++ b/v3/@claude-flow/cli/src/init/helpers-generator.ts
@@ -784,11 +784,22 @@ export function generateIntelligenceStub(): string {
"const path = require('path');",
"const os = require('os');",
'',
- "const DATA_DIR = path.join(process.cwd(), '.claude-flow', 'data');",
+ 'function resolveProjectRoot(startDir) {',
+ ' if (process.env.CLAUDE_PROJECT_DIR) return path.resolve(process.env.CLAUDE_PROJECT_DIR);',
+ ' var dir = path.resolve(startDir || process.cwd());',
+ ' while (true) {',
+ ' if (fs.existsSync(path.join(dir, ".git")) || fs.existsSync(path.join(dir, ".claude-flow"))) return dir;',
+ ' var parent = path.dirname(dir);',
+ ' if (parent === dir) return path.resolve(startDir || process.cwd());',
+ ' dir = parent;',
+ ' }',
+ '}',
+ "const PROJECT_ROOT = resolveProjectRoot(process.cwd());",
+ "const DATA_DIR = path.join(PROJECT_ROOT, '.claude-flow', 'data');",
"const STORE_PATH = path.join(DATA_DIR, 'auto-memory-store.json');",
"const RANKED_PATH = path.join(DATA_DIR, 'ranked-context.json');",
"const PENDING_PATH = path.join(DATA_DIR, 'pending-insights.jsonl');",
- "const SESSION_DIR = path.join(process.cwd(), '.claude-flow', 'sessions');",
+ "const SESSION_DIR = path.join(PROJECT_ROOT, '.claude-flow', 'sessions');",
"const SESSION_FILE = path.join(SESSION_DIR, 'current.json');",
'',
'function ensureDir(dir) {',
@@ -832,8 +843,8 @@ export function generateIntelligenceStub(): string {
' var entries = [];',
' var candidates = [',
' path.join(os.homedir(), ".claude", "projects"),',
- ' path.join(process.cwd(), ".claude-flow", "memory"),',
- ' path.join(process.cwd(), ".claude", "memory"),',
+ ' path.join(PROJECT_ROOT, ".claude-flow", "memory"),',
+ ' path.join(PROJECT_ROOT, ".claude", "memory"),',
' ];',
' for (var i = 0; i < candidates.length; i++) {',
' try {',
@@ -1474,4 +1485,3 @@ function main() {
main();
`;
}
-
diff --git a/v3/@claude-flow/cli/src/init/statusline-generator.ts b/v3/@claude-flow/cli/src/init/statusline-generator.ts
index a34b67edfa..ee01438ae2 100644
--- a/v3/@claude-flow/cli/src/init/statusline-generator.ts
+++ b/v3/@claude-flow/cli/src/init/statusline-generator.ts
@@ -54,6 +54,16 @@ function getInstalledCliVersionLocal(): string {
}
}
+function compareVersionsLocal(a: string, b: string): number {
+ const pa = a.split(/[.-]/).map(part => Number.parseInt(part, 10) || 0);
+ const pb = b.split(/[.-]/).map(part => Number.parseInt(part, 10) || 0);
+ for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+ const delta = (pa[i] ?? 0) - (pb[i] ?? 0);
+ if (delta !== 0) return delta;
+ }
+ return 0;
+}
+
/**
* Generate optimized statusline script
* Output format:
@@ -93,10 +103,12 @@ export function generateStatuslineScript(options: InitOptions): string {
// getInstalledCliVersionLocal() above β€” reuse the pattern for the
// same reason it exists there.
let helperContent: string | null = null;
+ let helperPackageRoot = '';
try {
const esmRequire = createRequire(import.meta.url);
const pkgJsonPath = esmRequire.resolve('@claude-flow/cli/package.json');
- const helperPath = path.join(path.dirname(pkgJsonPath), '.claude', 'helpers', 'statusline.cjs');
+ helperPackageRoot = path.dirname(pkgJsonPath);
+ const helperPath = path.join(helperPackageRoot, '.claude', 'helpers', 'statusline.cjs');
helperContent = fs.readFileSync(helperPath, 'utf-8');
} catch {
let dir = __dirname_sg;
@@ -105,7 +117,11 @@ export function generateStatuslineScript(options: InitOptions): string {
const pkg = JSON.parse(fs.readFileSync(path.join(dir, 'package.json'), 'utf-8'));
if (pkg && pkg.name === '@claude-flow/cli') {
const candidate = path.join(dir, '.claude', 'helpers', 'statusline.cjs');
- if (fs.existsSync(candidate)) { helperContent = fs.readFileSync(candidate, 'utf-8'); break; }
+ if (fs.existsSync(candidate)) {
+ helperPackageRoot = dir;
+ helperContent = fs.readFileSync(candidate, 'utf-8');
+ break;
+ }
}
} catch { /* keep climbing */ }
const parent = path.dirname(dir);
@@ -127,15 +143,18 @@ export function generateStatuslineScript(options: InitOptions): string {
// whatever the helper hard-codes) ships. Add a paired test in
// statusline-cost-display.test.ts before changing either token.
helperContent = helperContent.replace(/maxAgents: \d+,/, `maxAgents: ${maxAgents},`);
+ helperContent = helperContent.replace(
+ /const BAKED_INSTALL_ROOT = "[^"]*";/,
+ `const BAKED_INSTALL_ROOT = ${JSON.stringify(helperPackageRoot)};`,
+ );
// Only overwrite the helper's baked version if OURS resolves higher.
// Otherwise the substitution could DOWNGRADE (test environments where
// esmRequire.resolve happens to hit an older node_modules install would
- // clobber a fresh committed helper). Naive lexicographic compare β€” works
- // for canonical semver strings with same-width digit parts, which is
- // reliable at this stage of the version space.
+ // clobber a fresh committed helper). Compare numeric components:
+ // lexicographic comparison freezes 3.32.24 below 3.32.8 (#2811).
const helperVerMatch = helperContent.match(/let ver = "([^"]+)";/);
const helperVer = helperVerMatch ? helperVerMatch[1] : '';
- if (!helperVer || bakedVersion > helperVer) {
+ if (!helperVer || compareVersionsLocal(bakedVersion, helperVer) > 0) {
helperContent = helperContent.replace(/let ver = "[^"]+";/, `let ver = ${JSON.stringify(bakedVersion)};`);
}
diff --git a/v3/@claude-flow/cli/src/mcp-server.ts b/v3/@claude-flow/cli/src/mcp-server.ts
index 5b2014a9fc..3cd340e47c 100644
--- a/v3/@claude-flow/cli/src/mcp-server.ts
+++ b/v3/@claude-flow/cli/src/mcp-server.ts
@@ -79,6 +79,70 @@ const DEFAULT_OPTIONS: Required<MCPServerOptions> = {
timeout: 30000,
};
+export function parseMcpToolSelection(value: string | undefined): string[] | 'all' {
+ if (!value || value.trim().toLowerCase() === 'all') return 'all';
+ const selectors = value.split(',').map((item) => item.trim()).filter(Boolean);
+ return selectors.length > 0 ? selectors : 'all';
+}
+
+/**
+ * Apply the existing `--tools` contract to advertised schemas. A selector can
+ * be an exact tool name, a category, or a namespace prefix (`memory` matches
+ * `memory_store`). Execution remains registered internally; only the fixed
+ * per-request schema catalogue is reduced.
+ */
+export function filterAdvertisedMcpTools<T extends { name: string; category?: string }>(
+ tools: T[],
+ selection: string[] | 'all',
+): T[] {
+ if (selection === 'all') return tools;
+ const selectors = new Set(selection.map((item) => item.toLowerCase()));
+ return tools.filter((tool) => {
+ const name = tool.name.toLowerCase();
+ const category = tool.category?.toLowerCase();
+ return selectors.has(name)
+ || (category !== undefined && selectors.has(category))
+ || Array.from(selectors).some((selector) => name.startsWith(`${selector}_`));
+ });
+}
+
+export interface McpSchemaOverhead {
+ toolCount: number;
+ bytes: number;
+ estimatedTokens: number;
+ contextWindowTokens?: number;
+ ratio?: number;
+ risk: 'normal' | 'high';
+}
+
+/** Conservative JSON-size estimate for the fixed tools/list catalogue. */
+export function assessMcpSchemaOverhead(
+ tools: Array<{ name: string; description?: string; inputSchema?: unknown }>,
+ contextWindowTokens?: number,
+): McpSchemaOverhead {
+ const catalogue = tools.map((tool) => ({
+ name: tool.name,
+ description: tool.description,
+ inputSchema: tool.inputSchema,
+ }));
+ const bytes = Buffer.byteLength(JSON.stringify(catalogue), 'utf8');
+ const estimatedTokens = Math.ceil(bytes / 4);
+ const validWindow = Number.isFinite(contextWindowTokens) && Number(contextWindowTokens) > 0
+ ? Number(contextWindowTokens)
+ : undefined;
+ const ratio = validWindow ? estimatedTokens / validWindow : undefined;
+ return {
+ toolCount: tools.length,
+ bytes,
+ estimatedTokens,
+ ...(validWindow === undefined ? {} : { contextWindowTokens: validWindow }),
+ ...(ratio === undefined ? {} : { ratio }),
+ risk: (ratio !== undefined ? ratio >= 0.2 : estimatedTokens >= 8_000)
+ ? 'high'
+ : 'normal',
+ };
+}
+
/**
* MCP Server Manager
*
@@ -93,7 +157,14 @@ export class MCPServerManager extends EventEmitter {
constructor(options: MCPServerOptions = {}) {
super();
- this.options = { ...DEFAULT_OPTIONS, ...options };
+ // `options.tools`, populated by the `mcp start --tools` CLI flag, is
+ // spread last below and therefore takes precedence over this env fallback.
+ const environmentTools = parseMcpToolSelection(process.env.CLAUDE_FLOW_MCP_TOOLS);
+ this.options = {
+ ...DEFAULT_OPTIONS,
+ ...(environmentTools === 'all' ? {} : { tools: environmentTools }),
+ ...options,
+ };
}
/**
@@ -542,7 +613,7 @@ export class MCPServerManager extends EventEmitter {
};
case 'tools/list':
- const tools = listMCPTools();
+ const tools = filterAdvertisedMcpTools(listMCPTools(), this.options.tools);
return {
jsonrpc: '2.0',
id: message.id,
diff --git a/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts
index 922f08aeb3..28b9d88f55 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/embeddings-tools.ts
@@ -91,13 +91,23 @@ async function getRealEmbeddingFunction() {
}
// Generate real ONNX embedding (falls back to deterministic hash if ONNX unavailable)
-async function generateRealEmbedding(text: string, dimension: number): Promise<number[]> {
+type EmbeddingResult = {
+ embedding: number[];
+ backend: 'onnx' | 'mock';
+ model: string;
+};
+
+async function generateRealEmbedding(text: string, dimension: number): Promise<EmbeddingResult> {
const realFn = await getRealEmbeddingFunction();
if (realFn) {
try {
const result = await realFn(text);
- return result.embedding;
+ return {
+ embedding: result.embedding,
+ backend: (result as { backend?: 'onnx' | 'mock' }).backend ?? 'onnx',
+ model: result.model,
+ };
} catch {
// Fall through to fallback
}
@@ -118,7 +128,11 @@ async function generateRealEmbedding(text: string, dimension: number): Promise<n
// L2 normalize
const norm = Math.sqrt(embedding.reduce((sum, x) => sum + x * x, 0));
- return embedding.map(x => x / norm);
+ return {
+ embedding: embedding.map(x => x / norm),
+ backend: 'mock',
+ model: 'hash-fallback',
+ };
}
// Convert Euclidean embedding to PoincarΓ© ball
@@ -296,7 +310,8 @@ export const embeddingsTools: MCPTool[] = [
const useHyperbolic = input.hyperbolic === true && config.hyperbolic.enabled;
// Generate real ONNX embedding
- const embedding = await generateRealEmbedding(text, config.dimension);
+ const generated = await generateRealEmbedding(text, config.dimension);
+ const embedding = generated.embedding;
let result: number[];
let geometry: string;
@@ -314,6 +329,8 @@ export const embeddingsTools: MCPTool[] = [
embedding: result,
metadata: {
model: config.model,
+ embeddingBackend: generated.backend,
+ semanticGrounded: generated.backend === 'onnx',
dimension: config.dimension,
geometry,
curvature: useHyperbolic ? config.hyperbolic.curvature : null,
@@ -365,10 +382,14 @@ export const embeddingsTools: MCPTool[] = [
{ const v = validateText(text2, 'text2'); if (!v.valid) return { success: false, error: v.error }; }
// Generate real ONNX embeddings for both texts
- const [emb1, emb2] = await Promise.all([
+ const [generated1, generated2] = await Promise.all([
generateRealEmbedding(text1, config.dimension),
generateRealEmbedding(text2, config.dimension)
]);
+ const emb1 = generated1.embedding;
+ const emb2 = generated2.embedding;
+ const embeddingBackend =
+ generated1.backend === 'onnx' && generated2.backend === 'onnx' ? 'onnx' : 'mock';
let similarity: number;
let distance: number;
@@ -402,14 +423,21 @@ export const embeddingsTools: MCPTool[] = [
similarity,
distance,
metric,
+ embeddingBackend,
+ semanticGrounded: embeddingBackend === 'onnx',
texts: {
text1: { length: text1.length, preview: text1.slice(0, 50) },
text2: { length: text2.length, preview: text2.slice(0, 50) },
},
- interpretation: similarity > 0.8 ? 'very similar' :
- similarity > 0.6 ? 'similar' :
- similarity > 0.4 ? 'somewhat similar' :
- similarity > 0.2 ? 'different' : 'very different',
+ interpretation: embeddingBackend === 'onnx'
+ ? similarity > 0.8 ? 'very similar'
+ : similarity > 0.6 ? 'similar'
+ : similarity > 0.4 ? 'somewhat similar'
+ : similarity > 0.2 ? 'different' : 'very different'
+ : null,
+ warning: embeddingBackend === 'mock'
+ ? 'Hash fallback scores are deterministic but not semantically meaningful.'
+ : undefined,
};
},
},
@@ -487,6 +515,8 @@ export const embeddingsTools: MCPTool[] = [
})),
metadata: {
model: config.model,
+ embeddingBackend: queryEmbedding.backend,
+ semanticGrounded: queryEmbedding.backend === 'onnx',
topK,
threshold,
namespace: namespace || 'all',
@@ -494,6 +524,9 @@ export const embeddingsTools: MCPTool[] = [
indexType: config.hyperbolic.enabled ? 'HNSW (hyperbolic)' : 'HNSW (euclidean)',
resultCount: searchResult.results.length
},
+ warning: queryEmbedding.backend === 'mock'
+ ? 'Results use a hash fallback and are not semantically ranked.'
+ : undefined,
};
} catch {
// Database not available - return empty but truthful
@@ -504,12 +537,17 @@ export const embeddingsTools: MCPTool[] = [
results: [],
metadata: {
model: config.model,
+ embeddingBackend: queryEmbedding.backend,
+ semanticGrounded: queryEmbedding.backend === 'onnx',
topK,
threshold,
namespace: namespace || 'all',
searchTime: `${searchTime}ms`,
indexType: config.hyperbolic.enabled ? 'HNSW (hyperbolic)' : 'HNSW (euclidean)',
},
+ warning: queryEmbedding.backend === 'mock'
+ ? 'Hash fallback is active; semantic search is unavailable.'
+ : undefined,
message: 'No embeddings indexed yet. Use memory store to add documents.',
};
}
@@ -866,6 +904,8 @@ export const embeddingsTools: MCPTool[] = [
} catch { /* not installed */ }
const ruvectorEnabled = config.neural.ruvector?.enabled ?? false;
+ const backendProbe = await generateRealEmbedding('ruflo embedding backend probe', config.dimension);
+ const semanticGrounded = backendProbe.backend === 'onnx';
return {
success: true,
@@ -894,11 +934,20 @@ export const embeddingsTools: MCPTool[] = [
models: config.modelPath,
},
initializedAt: config.initialized,
+ embeddingBackend: backendProbe.backend,
+ semanticGrounded,
+ warning: semanticGrounded
+ ? undefined
+ : 'Hash fallback is active. Similarity scores are deterministic but not semantically meaningful.',
capabilities: {
onnxModels: ['Xenova/all-MiniLM-L6-v2', 'Xenova/all-mpnet-base-v2'],
geometries: ['euclidean', 'poincare'],
normalizations: ['L2', 'L1', 'minmax', 'zscore'],
- features: ['semantic search', 'hyperbolic projection', 'neural substrate'],
+ features: [
+ ...(semanticGrounded ? ['semantic search'] : []),
+ 'hyperbolic projection',
+ 'neural substrate',
+ ],
},
};
},
diff --git a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
index 03bb2d690b..0b59a10cfd 100644
--- a/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
+++ b/v3/@claude-flow/cli/src/mcp-tools/hooks-tools.ts
@@ -515,7 +515,14 @@ function loadMemoryStore(): MemoryStore {
*/
function getIntelligenceStatsFromMemory(): {
trajectories: { total: number; successful: number };
- patterns: { learned: number; categories: Record<string, number> };
+ patterns: {
+ learned: number;
+ successful: number;
+ failed: number;
+ unknown: number;
+ described: number;
+ categories: Record<string, number>;
+ };
memory: { indexSize: number; totalAccessCount: number; memorySizeBytes: number };
routing: { decisions: number; avgConfidence: number };
} {
@@ -556,6 +563,18 @@ function getIntelligenceStatsFromMemory(): {
const category = (e.metadata?.category as string) || 'general';
categories[category] = (categories[category] || 0) + 1;
});
+ const successfulPatterns = patternEntries.filter(e => e.metadata?.success === true).length;
+ const failedPatterns = patternEntries.filter(e => e.metadata?.success === false).length;
+ const describedPatterns = patternEntries.filter(e => {
+ if (typeof e.metadata?.task === 'string' && e.metadata.task.trim()) return true;
+ try {
+ const value = typeof e.value === 'string' ? JSON.parse(e.value) : e.value;
+ return typeof (value as Record<string, unknown> | null)?.task === 'string' &&
+ Boolean(String((value as Record<string, unknown>).task).trim());
+ } catch {
+ return false;
+ }
+ }).length;
// Count routing decisions
const routingEntries = entries.filter(e =>
@@ -595,6 +614,10 @@ function getIntelligenceStatsFromMemory(): {
},
patterns: {
learned: patternEntries.length,
+ successful: successfulPatterns,
+ failed: failedPatterns,
+ unknown: Math.max(0, patternEntries.length - successfulPatterns - failedPatterns),
+ described: describedPatterns,
categories,
},
memory: {
@@ -1215,22 +1238,28 @@ export const hooksMetrics: MCPTool = {
}
const topAgent = Object.entries(agentCounts).sort((a, b) => b[1] - a[1])[0]?.[0] ?? null;
- const successful = stats.trajectories.successful;
- const total = stats.trajectories.total;
- const failed = Math.max(0, total - successful);
-
return {
_real: true,
_dataSource: 'intelligence-stats + routing-outcomes',
period,
patterns: {
total: stats.patterns.learned,
- successful,
- failed,
+ successful: stats.patterns.successful,
+ failed: stats.patterns.failed,
+ unknown: stats.patterns.unknown,
+ described: stats.patterns.described,
+ descriptionCoverage: stats.patterns.learned > 0
+ ? stats.patterns.described / stats.patterns.learned
+ : null,
avgConfidence: stats.routing.avgConfidence || null,
},
agents: {
- routingAccuracy: stats.routing.avgConfidence || null,
+ // Confidence is a model self-score, not observed routing accuracy
+ // (#2809). Keep the old key as an explicit null for compatibility
+ // while exposing the truthful additive field.
+ routingAccuracy: null,
+ averageConfidence: stats.routing.avgConfidence || null,
+ outcomeSuccessRate: successRate,
totalRoutes: stats.routing.decisions,
topAgent,
},
@@ -1239,7 +1268,7 @@ export const hooksMetrics: MCPTool = {
successRate,
avgRiskScore: null,
},
- _note: total === 0 && totalCommands === 0
+ _note: stats.patterns.learned === 0 && totalCommands === 0
? 'No metrics data collected yet. Run hooks_post-task / hooks_intelligence_trajectory-end / hooks_route to populate.'
: undefined,
lastUpdated: new Date().toISOString(),
@@ -1442,6 +1471,7 @@ export const hooksPostTask: MCPTool = {
const bridge = await import('../memory/memory-bridge.js');
feedbackResult = await bridge.bridgeRecordFeedback({
taskId,
+ task: (params.task as string) || undefined,
success,
quality,
agent,
@@ -3261,7 +3291,7 @@ export const hooksIntelligenceStats: MCPTool = {
} catch {
memoryStats = {
trajectories: { total: 0, successful: 0 },
- patterns: { learned: 0, categories: {} },
+ patterns: { learned: 0, successful: 0, failed: 0, unknown: 0, described: 0, categories: {} },
memory: { indexSize: 0, totalAccessCount: 0, memorySizeBytes: 0 },
routing: { decisions: 0, avgConfidence: 0 },
};
diff --git a/v3/@claude-flow/cli/src/memory/memory-bridge.ts b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
index 68467d0280..ce8d450cb4 100644
--- a/v3/@claude-flow/cli/src/memory/memory-bridge.ts
+++ b/v3/@claude-flow/cli/src/memory/memory-bridge.ts
@@ -2084,6 +2084,8 @@ export async function bridgeSearchPatterns(options: {
*/
export async function bridgeRecordFeedback(options: {
taskId: string;
+ /** Human-readable task text used as the semantic learning signal. */
+ task?: string;
success: boolean;
quality: number;
agent?: string;
@@ -2118,12 +2120,16 @@ export async function bridgeRecordFeedback(options: {
try {
const intelligence = await import('./intelligence.js');
const verdict = options.success ? 'success' : 'failure';
+ const taskContext = options.task?.trim();
const recorded = await intelligence.recordTrajectory(
[{
type: 'action',
- content: `Task ${options.taskId} completed by ${options.agent || 'unknown'} β€” success=${options.success}, quality=${options.quality.toFixed(3)}`,
+ // Put the task description first so the embedding represents the
+ // work, not just the bookkeeping suffix (#2812).
+ content: `${taskContext ? `${taskContext} β€” ` : ''}Task ${options.taskId} completed by ${options.agent || 'unknown'} β€” success=${options.success}, quality=${options.quality.toFixed(3)}`,
metadata: {
taskId: options.taskId,
+ task: taskContext,
agent: options.agent,
quality: options.quality,
duration: options.duration,
diff --git a/v3/@claude-flow/cli/src/services/memory-distillation.ts b/v3/@claude-flow/cli/src/services/memory-distillation.ts
index 97a9a94c26..76e2728114 100644
--- a/v3/@claude-flow/cli/src/services/memory-distillation.ts
+++ b/v3/@claude-flow/cli/src/services/memory-distillation.ts
@@ -3,7 +3,8 @@
*
* Turns raw `memory_entries` (what ruflo has been RECORDING for thousands of
* commits) into the structured intelligence substrate it has never populated:
- * `episodes` β†’ `reasoning_patterns` (+ `pattern_embeddings`) β†’ `causal_edges`.
+ * `episodes` (+ `episode_embeddings`) β†’ `reasoning_patterns`
+ * (+ `pattern_embeddings`) β†’ `causal_edges`.
* This is the DISTILL/CONSOLIDATE half of the RETRIEVE→JUDGE→DISTILL→CONSOLIDATE
* pipeline; RETRIEVE (embeddings) was already populated, the rest was empty
* because the daemon's `consolidate` worker was a stub (see ADR-174 root cause).
@@ -52,6 +53,7 @@ export interface DistillOptions {
export interface DistillReport {
processed: number;
episodes: number;
+ episodeEmbeddings: number;
patterns: number;
patternEmbeddings: number;
causalEdges: number;
@@ -81,7 +83,8 @@ interface Cluster {
function emptyReport(dryRun: boolean, extra: Partial<DistillReport> = {}): DistillReport {
return {
- processed: 0, episodes: 0, patterns: 0, patternEmbeddings: 0, causalEdges: 0,
+ processed: 0, episodes: 0, episodeEmbeddings: 0,
+ patterns: 0, patternEmbeddings: 0, causalEdges: 0,
promoted: 0, byProvenance: {}, namespaces: [], dryRun, spendUsd: 0, ...extra,
};
}
@@ -114,6 +117,20 @@ function judgeFeedback(content: string): { success: boolean; reward: number } {
return { success: true, reward: 0.5 };
}
+/** Preserve an execution-observed lesson for Reflexion without presenting
+ * proxy/structural summaries as genuine self-critique. */
+function feedbackCritique(content: string): string {
+ try {
+ const value = JSON.parse(content) as Record<string, unknown>;
+ for (const key of ['critique', 'error', 'message', 'summary', 'stderr']) {
+ if (typeof value[key] === 'string' && value[key].trim()) {
+ return value[key].trim().slice(0, 2000);
+ }
+ }
+ } catch { /* retain the original execution feedback below */ }
+ return `Observed execution feedback: ${content}`.slice(0, 2000);
+}
+
/**
* Distill accumulated memory into the structured intelligence tables.
* Incremental, $0, transactional, provenance-tagged.
@@ -150,7 +167,6 @@ export async function runDistillation(options: DistillOptions): Promise<DistillR
for (const t of ['episodes', 'reasoning_patterns', 'pattern_embeddings', 'causal_edges']) {
if (!tableExists(t)) { db.close(); return { ...report, skipped: `target table ${t} missing (agentdb schema not initialised)` }; }
}
-
// Safety gate: never distill into a structurally-corrupt DB.
const qc = db.prepare('PRAGMA quick_check(1)').get() as Record<string, string> | undefined;
if (qc && String(Object.values(qc)[0] ?? '').toLowerCase() !== 'ok') {
@@ -158,6 +174,18 @@ export async function runDistillation(options: DistillOptions): Promise<DistillR
return { ...report, corrupt: true, skipped: 'memory DB reports corruption β€” run recoverMemoryDatabase first' };
}
+ // #2677 β€” older AgentDB stores may have episodes but no embedding table.
+ // Create the stable AgentDB v1 table only after the corruption gate, and
+ // never create it during a dry-run.
+ if (!dryRun && !tableExists('episode_embeddings')) {
+ db.exec(`CREATE TABLE episode_embeddings (
+ episode_id INTEGER PRIMARY KEY,
+ embedding BLOB NOT NULL,
+ embedding_model TEXT DEFAULT 'all-MiniLM-L6-v2',
+ FOREIGN KEY(episode_id) REFERENCES episodes(id) ON DELETE CASCADE
+ )`);
+ }
+
// M0: incremental cursor table (per namespace, by monotonic rowid).
db.exec(`CREATE TABLE IF NOT EXISTS distill_state (
namespace TEXT PRIMARY KEY,
@@ -179,7 +207,10 @@ export async function runDistillation(options: DistillOptions): Promise<DistillR
);
const insEpisode = db.prepare(
- 'INSERT INTO episodes (session_id, task, input, output, reward, success, tags, metadata) VALUES (?,?,?,?,?,?,?,?)',
+ 'INSERT INTO episodes (session_id, task, input, output, critique, reward, success, tags, metadata) VALUES (?,?,?,?,?,?,?,?,?)',
+ );
+ const insEpisodeEmbedding = dryRun ? null : db.prepare(
+ 'INSERT OR REPLACE INTO episode_embeddings (episode_id, embedding) VALUES (?, ?)',
);
const insPattern = db.prepare(
'INSERT INTO reasoning_patterns (task_type, approach, success_rate, uses, avg_reward, tags, metadata) VALUES (?,?,?,?,?,?,?)',
@@ -189,6 +220,49 @@ export async function runDistillation(options: DistillOptions): Promise<DistillR
'INSERT INTO causal_edges (from_memory_id, from_memory_type, to_memory_id, to_memory_type, similarity, confidence, mechanism, metadata) VALUES (?,?,?,?,?,?,?,?)',
);
+ // Repair episodes produced by older distillation releases. Their metadata
+ // records sourceIds; if that provenance is absent, exact input matching is
+ // a conservative fallback. Never invent a vector or call a model.
+ if (!dryRun) {
+ const missingEpisodes = db.prepare(`
+ SELECT e.id, e.input, e.metadata
+ FROM episodes e
+ LEFT JOIN episode_embeddings ee ON ee.episode_id = e.id
+ WHERE ee.episode_id IS NULL AND e.session_id LIKE 'distill:%'
+ `).all() as Array<{ id: number; input: string | null; metadata: string | null }>;
+ const embeddingById = db.prepare('SELECT embedding FROM memory_entries WHERE id = ? AND embedding IS NOT NULL');
+ const embeddingByContent = db.prepare(
+ 'SELECT embedding FROM memory_entries WHERE content = ? AND embedding IS NOT NULL LIMIT 1',
+ );
+ const missingCritiques = db.prepare(`
+ SELECT id, input FROM episodes
+ WHERE session_id LIKE 'distill:feedback%'
+ AND length(trim(coalesce(critique,''))) = 0
+ `).all() as Array<{ id: number; input: string | null }>;
+ const updateCritique = db.prepare('UPDATE episodes SET critique = ? WHERE id = ?');
+ const backfill = db.transaction(() => {
+ for (const episode of missingEpisodes) {
+ let sourceId: string | undefined;
+ try {
+ const metadata = JSON.parse(episode.metadata ?? '{}') as { sourceIds?: unknown };
+ if (Array.isArray(metadata.sourceIds) && typeof metadata.sourceIds[0] === 'string') {
+ sourceId = metadata.sourceIds[0];
+ }
+ } catch { /* use exact-content fallback */ }
+ let raw = sourceId ? embeddingById.get(sourceId)?.embedding : undefined;
+ if (!raw) raw = embeddingByContent.get(episode.input ?? '')?.embedding;
+ const vector = parseEmbedding(raw);
+ if (!vector) continue;
+ insEpisodeEmbedding!.run(episode.id, Buffer.from(Float32Array.from(vector).buffer));
+ report.episodeEmbeddings++;
+ }
+ for (const episode of missingCritiques) {
+ updateCritique.run(feedbackCritique(episode.input ?? ''), episode.id);
+ }
+ });
+ backfill();
+ }
+
let remaining = typeof maxEntries === 'number' ? maxEntries : Infinity;
for (const ns of nsList) {
@@ -265,10 +339,18 @@ export async function runDistillation(options: DistillOptions): Promise<DistillR
const epInfo = insEpisode.run(
`distill:${ns}`, approach, cl.rep.content.slice(0, 2000), '',
+ cl.provenance === 'oracle:test-exec' ? feedbackCritique(cl.rep.content) : null,
avgReward, promoted && cl.successCount > 0 ? 1 : 0,
JSON.stringify(distilled.labels), JSON.stringify(provMeta),
);
report.episodes++;
+ const epId = Number(epInfo.lastInsertRowid);
+
+ // ReflexionMemory.retrieveRelevant() INNER JOINs this table.
+ // Reuse the source embedding so every distilled episode is
+ // immediately retrievable without an embedding-model call.
+ insEpisodeEmbedding!.run(epId, Buffer.from(Float32Array.from(embVec).buffer));
+ report.episodeEmbeddings++;
const patInfo = insPattern.run(
taskType, approach, successRate, uses, avgReward,
@@ -289,7 +371,6 @@ export async function runDistillation(options: DistillOptions): Promise<DistillR
// rowids). Explicitly typed co-occurrence / proxy-tier / non-
// promoted: may rank retrieval, must NOT justify autonomous action
// (ADR-174 edge contract).
- const epId = Number(epInfo.lastInsertRowid);
if (prevEpId !== null) {
insEdge.run(
prevEpId, 'episode', epId, 'episode',
diff --git a/v3/@claude-flow/cli/src/services/worker-daemon.ts b/v3/@claude-flow/cli/src/services/worker-daemon.ts
index 8e257f6281..7ff6d52bc4 100644
--- a/v3/@claude-flow/cli/src/services/worker-daemon.ts
+++ b/v3/@claude-flow/cli/src/services/worker-daemon.ts
@@ -1744,6 +1744,7 @@ export class WorkerDaemon extends EventEmitter {
// instead of becoming their own distinct pattern.
duplicatesRemoved: Math.max(0, report.processed - report.patterns),
episodes: report.episodes,
+ episodeEmbeddings: report.episodeEmbeddings,
patternEmbeddings: report.patternEmbeddings,
causalEdges: report.causalEdges,
promoted: report.promoted,
diff --git a/v3/@claude-flow/codex/.agents/skills/github-automation/SKILL.md b/v3/@claude-flow/codex/.agents/skills/github-automation/SKILL.md
new file mode 100644
index 0000000000..e1f2df511a
--- /dev/null
+++ b/v3/@claude-flow/codex/.agents/skills/github-automation/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: github-automation
+description: >
+ GitHub workflow automation for issues, pull requests, CI, and releases.
+ Use when: repository hosting actions are explicitly requested.
+ Skip when: local git operations are sufficient or publishing is unauthorized.
+---
+
+# GitHub Automation Skill
+
+## Purpose
+Automate GitHub workflows while keeping external writes explicit and scoped.
+
+## Commands
+
+### Create Pull Request
+
+```bash
+gh pr create --draft
+```
+
+### Inspect Checks
+
+```bash
+gh pr checks
+```
+
+## Best Practices
+1. Confirm repository and branch before external writes
+2. Inspect CI evidence before changing workflows
+3. Never publish, merge, or close without authorization
+4. Report the exact resulting URL or identifier
diff --git a/v3/@claude-flow/codex/.agents/skills/performance-analysis/SKILL.md b/v3/@claude-flow/codex/.agents/skills/performance-analysis/SKILL.md
new file mode 100644
index 0000000000..e47cd6badf
--- /dev/null
+++ b/v3/@claude-flow/codex/.agents/skills/performance-analysis/SKILL.md
@@ -0,0 +1,32 @@
+---
+name: performance-analysis
+description: >
+ Performance profiling, benchmarking, and optimization.
+ Use when: slow operations, regressions, memory pressure, release validation.
+ Skip when: early prototyping, documentation, configuration-only changes.
+---
+
+# Performance Analysis Skill
+
+## Purpose
+Measure before optimizing and preserve reproducible benchmark evidence.
+
+## Commands
+
+### Run Benchmark Suite
+
+```bash
+npx @claude-flow/cli performance benchmark --suite all
+```
+
+### Profile Code
+
+```bash
+npx @claude-flow/cli performance profile --target ./src
+```
+
+## Best Practices
+1. Capture a baseline before changing code
+2. Use identical inputs and environments
+3. Report variance, not only the fastest result
+4. Re-run correctness tests after optimization
diff --git a/v3/@claude-flow/codex/src/dual-mode/cli.ts b/v3/@claude-flow/codex/src/dual-mode/cli.ts
index 9f12aa02ea..4713c59568 100644
--- a/v3/@claude-flow/codex/src/dual-mode/cli.ts
+++ b/v3/@claude-flow/codex/src/dual-mode/cli.ts
@@ -5,6 +5,9 @@
import { Command } from 'commander';
import chalk from 'chalk';
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
import {
DualModeOrchestrator,
DualModeConfig,
@@ -111,7 +114,7 @@ function createRunCommand(): Command {
workers = getTemplateWorkers(templateName, task);
taskContext = `Template: ${templateName}, Task: ${task}`;
} else if (options.config) {
- const configData = await import(options.config);
+ const configData = await loadWorkerConfig(options.config, process.cwd());
workers = configData.workers;
taskContext = configData.taskContext || options.task || 'Collaborative task';
} else {
@@ -177,6 +180,26 @@ function createRunCommand(): Command {
});
}
+export async function loadWorkerConfig(
+ configPath: string,
+ cwd = process.cwd(),
+): Promise<{ workers: WorkerConfig[]; taskContext?: string }> {
+ const absolute = path.resolve(cwd, configPath);
+ const loaded = path.extname(absolute).toLowerCase() === '.json'
+ ? JSON.parse(await readFile(absolute, 'utf8'))
+ : await import(pathToFileURL(absolute).href);
+ const config = loaded.default && typeof loaded.default === 'object'
+ ? loaded.default
+ : loaded;
+ if (!Array.isArray(config.workers)) {
+ throw new Error(`Dual-mode config must export a workers array: ${absolute}`);
+ }
+ return {
+ workers: config.workers,
+ ...(typeof config.taskContext === 'string' ? { taskContext: config.taskContext } : {}),
+ };
+}
+
/**
* List available templates
*/
diff --git a/v3/@claude-flow/codex/src/dual-mode/orchestrator.ts b/v3/@claude-flow/codex/src/dual-mode/orchestrator.ts
index 080c57c107..032bd97739 100644
--- a/v3/@claude-flow/codex/src/dual-mode/orchestrator.ts
+++ b/v3/@claude-flow/codex/src/dual-mode/orchestrator.ts
@@ -49,6 +49,8 @@ export interface WorkerResult {
export interface DualModeConfig {
projectPath: string;
+ /** One database shared by bootstrap, collection, policy, and worker CLIs. */
+ memoryDbPath?: string;
maxConcurrent?: number;
sharedNamespace?: string;
timeout?: number;
@@ -90,6 +92,11 @@ export class DualModeOrchestrator extends EventEmitter {
}
this.config = {
projectPath: config.projectPath,
+ memoryDbPath: path.resolve(
+ config.memoryDbPath
+ ?? process.env.CLAUDE_FLOW_DB_PATH
+ ?? path.join(config.projectPath, '.claude-flow', 'dual-mode-memory.db'),
+ ),
maxConcurrent: config.maxConcurrent ?? 4,
sharedNamespace: config.sharedNamespace ?? 'collaboration',
timeout: config.timeout ?? 300000, // 5 minutes
@@ -107,7 +114,8 @@ export class DualModeOrchestrator extends EventEmitter {
* Initialize shared memory for collaboration
*/
async initializeSharedMemory(taskContext: string): Promise<void> {
- const { projectPath, sharedNamespace } = this.config;
+ const { projectPath, sharedNamespace, memoryDbPath } = this.config;
+ fs.mkdirSync(path.dirname(memoryDbPath), { recursive: true });
// Initialize memory database
await this.runCommand(
@@ -478,7 +486,11 @@ Remember: Other agents depend on your results in shared memory. Be concise and s
*/
private runCommand(command: string, args: string[], cwd: string): Promise<string> {
return new Promise((resolve, reject) => {
- const proc = spawn(command, args, { cwd, stdio: ['pipe', 'pipe', 'pipe'] });
+ const proc = spawn(command, args, {
+ cwd,
+ env: this.sharedEnvironment(),
+ stdio: ['pipe', 'pipe', 'pipe'],
+ });
let output = '';
let error = '';
@@ -576,6 +588,7 @@ Remember: Other agents depend on your results in shared memory. Be concise and s
env[name] = value;
}
env.FORCE_COLOR = '0';
+ env.CLAUDE_FLOW_DB_PATH = this.config.memoryDbPath;
env.CLAUDE_FLOW_PRINCIPAL_ID = `agent:${worker.id}`;
env.CLAUDE_FLOW_CAPABILITY_ENVELOPE = JSON.stringify(
this.resolveWorkerEnvelope(worker),
@@ -583,6 +596,14 @@ Remember: Other agents depend on your results in shared memory. Be concise and s
return env;
}
+ /** Keep every Ruflo subprocess on the same collaboration database. */
+ private sharedEnvironment(): NodeJS.ProcessEnv {
+ return {
+ ...process.env,
+ CLAUDE_FLOW_DB_PATH: this.config.memoryDbPath,
+ };
+ }
+
/**
* Stop all running workers
*/
diff --git a/v3/@claude-flow/codex/src/generators/skill-md.ts b/v3/@claude-flow/codex/src/generators/skill-md.ts
index 8d6beb9f83..531b70f9aa 100644
--- a/v3/@claude-flow/codex/src/generators/skill-md.ts
+++ b/v3/@claude-flow/codex/src/generators/skill-md.ts
@@ -1,14 +1,32 @@
/**
* @claude-flow/codex - SKILL.md Generator
*
- * Generates SKILL.md files for OpenAI Codex CLI skills
- * Uses YAML frontmatter for metadata
+ * Custom skills are rendered from typed options. Built-in skills use the
+ * packaged `.agents/skills` trees as their canonical definitions so direct
+ * generation, project initialization, and npm artifacts cannot drift.
*/
-import type { SkillMdOptions, SkillCommand } from '../types.js';
+import { readdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import type { BuiltInSkill, SkillMdOptions, SkillCommand } from '../types.js';
+
+export const BUILT_IN_SKILL_NAMES: readonly BuiltInSkill[] = [
+ 'swarm-orchestration',
+ 'memory-management',
+ 'sparc-methodology',
+ 'security-audit',
+ 'performance-analysis',
+ 'github-automation',
+];
+
+const BUILT_IN_SKILLS_ROOT = path.resolve(
+ path.dirname(fileURLToPath(import.meta.url)),
+ '../../.agents/skills',
+);
/**
- * Generate a SKILL.md file based on the provided options
+ * Generate a SKILL.md file based on the provided options.
*/
export async function generateSkillMd(options: SkillMdOptions): Promise<string> {
const {
@@ -24,10 +42,7 @@ export async function generateSkillMd(options: SkillMdOptions): Promise<string>
commands = [],
} = options;
- // Derive discovery tags from the skill name when not supplied explicitly.
const tagList = tags && tags.length > 0 ? tags : name.split('-').filter(Boolean);
-
- // Build YAML frontmatter
const triggerText = triggers.length > 0
? `Use when: ${triggers.join(', ')}.`
: '';
@@ -46,22 +61,10 @@ description: >
${skipText}
---`;
- // Build commands section
- const commandsSection = commands.length > 0
- ? buildCommandsSection(commands)
- : '';
-
- // Build scripts section
- const scriptsSection = scripts.length > 0
- ? buildScriptsSection(scripts)
- : '';
-
- // Build references section
- const referencesSection = references.length > 0
- ? buildReferencesSection(references)
- : '';
+ const commandsSection = commands.length > 0 ? buildCommandsSection(commands) : '';
+ const scriptsSection = scripts.length > 0 ? buildScriptsSection(scripts) : '';
+ const referencesSection = references.length > 0 ? buildReferencesSection(references) : '';
- // Combine all sections
return `${frontmatter}
# ${formatSkillName(name)} Skill
@@ -85,9 +88,6 @@ ${referencesSection}
`;
}
-/**
- * Build the commands section of the SKILL.md
- */
function buildCommandsSection(commands: SkillCommand[]): string {
const lines = commands.map(cmd => {
let block = `### ${cmd.name}\n${cmd.description}\n\n\`\`\`bash\n${cmd.command}\n\`\`\``;
@@ -104,9 +104,6 @@ ${lines.join('\n\n')}
`;
}
-/**
- * Build the scripts section
- */
function buildScriptsSection(scripts: { name: string; path: string; description: string }[]): string {
const lines = scripts.map(s => `| \`${s.name}\` | \`${s.path}\` | ${s.description} |`);
@@ -119,9 +116,6 @@ ${lines.join('\n')}
`;
}
-/**
- * Build the references section
- */
function buildReferencesSection(references: { name: string; path: string; description?: string }[]): string {
const lines = references.map(r =>
`| \`${r.name}\` | \`${r.path}\` | ${r.description ?? ''} |`
@@ -136,9 +130,6 @@ ${lines.join('\n')}
`;
}
-/**
- * Format skill name for display (kebab-case to Title Case)
- */
function formatSkillName(name: string): string {
return name
.split('-')
@@ -146,845 +137,96 @@ function formatSkillName(name: string): string {
.join(' ');
}
+async function readPayloadTree(root: string): Promise<Record<string, string>> {
+ const payload: Record<string, string> = {};
+
+ async function visit(directory: string): Promise<void> {
+ let entries;
+ try {
+ entries = await readdir(directory, { withFileTypes: true });
+ } catch (error) {
+ const code = (error as NodeJS.ErrnoException).code;
+ if (code === 'ENOENT') return;
+ throw error;
+ }
+
+ for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+ const absolute = path.join(directory, entry.name);
+ if (entry.isSymbolicLink()) {
+ throw new Error(`Built-in skill payload cannot contain symlinks: ${absolute}`);
+ }
+ if (entry.isDirectory()) {
+ await visit(absolute);
+ } else if (entry.isFile()) {
+ const relative = path.relative(root, absolute);
+ if (relative.startsWith('..') || path.isAbsolute(relative)) {
+ throw new Error(`Built-in skill payload escapes its root: ${absolute}`);
+ }
+ const payloadPath = relative.split(path.sep).join('/');
+ payload[payloadPath] = await readFile(absolute, 'utf8');
+ }
+ }
+ }
+
+ await visit(root);
+ return payload;
+}
+
/**
- * Generate a skill from a built-in template
+ * Read one canonical built-in tree from the package payload.
*/
export async function generateBuiltInSkill(
- skillName: string
+ skillName: string,
): Promise<{ skillMd: string; scripts: Record<string, string>; references: Record<string, string> }> {
- const skillTemplates: Record<string, SkillMdOptions> = {
- 'swarm-orchestration': {
- name: 'swarm-orchestration',
- description: 'Multi-agent swarm coordination for complex tasks. Uses hierarchical topology with specialized agents to break down and execute complex work across multiple files and modules.',
- triggers: [
- '3+ files need changes',
- 'new feature implementation',
- 'cross-module refactoring',
- 'API changes with tests',
- 'security-related changes',
- 'performance optimization across codebase',
- 'database schema changes',
- ],
- skipWhen: [
- 'single file edits',
- 'simple bug fixes (1-2 lines)',
- 'documentation updates',
- 'configuration changes',
- 'quick exploration',
- ],
- commands: [
- {
- name: 'Initialize Swarm',
- description: 'Start a new swarm with hierarchical topology (anti-drift)',
- command: 'npx ruflo swarm init --topology hierarchical --max-agents 8 --strategy specialized',
- example: 'npx ruflo swarm init --topology hierarchical --max-agents 6 --strategy specialized',
- },
- {
- name: 'Route Task',
- description: 'Route a task to the appropriate agents based on task type',
- command: 'npx @claude-flow/cli hooks route --task "[task description]"',
- example: 'npx @claude-flow/cli hooks route --task "implement OAuth2 authentication flow"',
- },
- {
- name: 'Spawn Agent',
- description: 'Spawn a specific agent type',
- command: 'npx @claude-flow/cli agent spawn --type [type] --name [name]',
- example: 'npx @claude-flow/cli agent spawn --type coder --name impl-auth',
- },
- {
- name: 'Monitor Status',
- description: 'Check the current swarm status',
- command: 'npx @claude-flow/cli swarm status --verbose',
- },
- {
- name: 'Orchestrate Task',
- description: 'Orchestrate a task across multiple agents',
- command: 'npx @claude-flow/cli task orchestrate --task "[task]" --strategy adaptive',
- example: 'npx @claude-flow/cli task orchestrate --task "refactor auth module" --strategy parallel --max-agents 4',
- },
- {
- name: 'List Agents',
- description: 'List all active agents',
- command: 'npx @claude-flow/cli agent list --filter active',
- },
- ],
- scripts: [
- {
- name: 'swarm-start',
- path: '.agents/scripts/swarm-start.sh',
- description: 'Initialize swarm with default settings',
- },
- {
- name: 'swarm-monitor',
- path: '.agents/scripts/swarm-monitor.sh',
- description: 'Real-time swarm monitoring dashboard',
- },
- ],
- references: [
- {
- name: 'Agent Types',
- path: 'docs/agents.md',
- description: 'Complete list of agent types and capabilities',
- },
- {
- name: 'Topology Guide',
- path: 'docs/topology.md',
- description: 'Swarm topology configuration guide',
- },
- ],
- },
- 'memory-management': {
- name: 'memory-management',
- description: 'AgentDB memory system with HNSW vector search. Provides 150x-12,500x faster pattern retrieval, persistent storage, and semantic search capabilities for learning and knowledge management.',
- triggers: [
- 'need to store successful patterns',
- 'searching for similar solutions',
- 'semantic lookup of past work',
- 'learning from previous tasks',
- 'sharing knowledge between agents',
- 'building knowledge base',
- ],
- skipWhen: [
- 'no learning needed',
- 'ephemeral one-off tasks',
- 'external data sources available',
- 'read-only exploration',
- ],
- commands: [
- {
- name: 'Store Pattern',
- description: 'Store a pattern or knowledge item in memory',
- command: 'npx @claude-flow/cli memory store --key "[key]" --value "[value]" --namespace patterns',
- example: 'npx @claude-flow/cli memory store --key "auth-jwt-pattern" --value "JWT validation with refresh tokens" --namespace patterns',
- },
- {
- name: 'Semantic Search',
- description: 'Search memory using semantic similarity',
- command: 'npx @claude-flow/cli memory search --query "[search terms]" --limit 10',
- example: 'npx @claude-flow/cli memory search --query "authentication best practices" --limit 5',
- },
- {
- name: 'Retrieve Entry',
- description: 'Retrieve a specific memory entry by key',
- command: 'npx @claude-flow/cli memory get --key "[key]" --namespace [namespace]',
- example: 'npx @claude-flow/cli memory get --key "auth-jwt-pattern" --namespace patterns',
- },
- {
- name: 'List Entries',
- description: 'List all entries in a namespace',
- command: 'npx @claude-flow/cli memory list --namespace [namespace]',
- example: 'npx @claude-flow/cli memory list --namespace patterns --limit 20',
- },
- {
- name: 'Delete Entry',
- description: 'Delete a memory entry',
- command: 'npx @claude-flow/cli memory delete --key "[key]" --namespace [namespace]',
- },
- {
- name: 'Initialize HNSW Index',
- description: 'Initialize HNSW vector search index',
- command: 'npx @claude-flow/cli memory init --enable-hnsw',
- },
- {
- name: 'Memory Stats',
- description: 'Show memory usage statistics',
- command: 'npx @claude-flow/cli memory stats',
- },
- {
- name: 'Export Memory',
- description: 'Export memory to JSON',
- command: 'npx @claude-flow/cli memory export --output memory-backup.json',
- },
- ],
- scripts: [
- {
- name: 'memory-backup',
- path: '.agents/scripts/memory-backup.sh',
- description: 'Backup memory to external storage',
- },
- {
- name: 'memory-consolidate',
- path: '.agents/scripts/memory-consolidate.sh',
- description: 'Consolidate and optimize memory',
- },
- ],
- references: [
- {
- name: 'HNSW Guide',
- path: 'docs/hnsw.md',
- description: 'HNSW vector search configuration',
- },
- {
- name: 'Memory Schema',
- path: 'docs/memory-schema.md',
- description: 'Memory namespace and schema reference',
- },
- ],
- },
- 'sparc-methodology': {
- name: 'sparc-methodology',
- description: 'SPARC development workflow: Specification, Pseudocode, Architecture, Refinement, Completion. A structured approach for complex implementations that ensures thorough planning before coding.',
- triggers: [
- 'new feature implementation',
- 'complex implementations',
- 'architectural changes',
- 'system redesign',
- 'integration work',
- 'unclear requirements',
- ],
- skipWhen: [
- 'simple bug fixes',
- 'documentation updates',
- 'configuration changes',
- 'well-defined small tasks',
- 'routine maintenance',
- ],
- commands: [
- {
- name: 'Specification Phase',
- description: 'Define requirements, acceptance criteria, and constraints',
- command: 'npx @claude-flow/cli hooks route --task "specification: [requirements]"',
- example: 'npx @claude-flow/cli hooks route --task "specification: user authentication with OAuth2, MFA, and session management"',
- },
- {
- name: 'Pseudocode Phase',
- description: 'Write high-level pseudocode for the implementation',
- command: 'npx @claude-flow/cli hooks route --task "pseudocode: [feature]"',
- example: 'npx @claude-flow/cli hooks route --task "pseudocode: OAuth2 login flow with token refresh"',
- },
- {
- name: 'Architecture Phase',
- description: 'Design system structure, interfaces, and dependencies',
- command: 'npx @claude-flow/cli hooks route --task "architecture: [design]"',
- example: 'npx @claude-flow/cli hooks route --task "architecture: auth module with service layer, repository, and API endpoints"',
- },
- {
- name: 'Refinement Phase',
- description: 'Iterate on the design based on feedback',
- command: 'npx @claude-flow/cli hooks route --task "refinement: [feedback]"',
- example: 'npx @claude-flow/cli hooks route --task "refinement: add rate limiting and brute force protection"',
- },
- {
- name: 'Completion Phase',
- description: 'Finalize implementation with tests and documentation',
- command: 'npx @claude-flow/cli hooks route --task "completion: [final checks]"',
- example: 'npx @claude-flow/cli hooks route --task "completion: verify all tests pass, update API docs, security review"',
- },
- {
- name: 'SPARC Coordinator',
- description: 'Spawn SPARC coordinator agent',
- command: 'npx @claude-flow/cli agent spawn --type sparc-coord --name sparc-lead',
- },
- ],
- scripts: [
- {
- name: 'sparc-init',
- path: '.agents/scripts/sparc-init.sh',
- description: 'Initialize SPARC workflow for a new feature',
- },
- {
- name: 'sparc-review',
- path: '.agents/scripts/sparc-review.sh',
- description: 'Run SPARC phase review checklist',
- },
- ],
- references: [
- {
- name: 'SPARC Overview',
- path: 'docs/sparc.md',
- description: 'Complete SPARC methodology guide',
- },
- {
- name: 'Phase Templates',
- path: 'docs/sparc-templates.md',
- description: 'Templates for each SPARC phase',
- },
- ],
- },
- 'security-audit': {
- name: 'security-audit',
- description: 'Comprehensive security scanning and vulnerability detection. Includes input validation, path traversal prevention, CVE detection, and secure coding pattern enforcement.',
- triggers: [
- 'authentication implementation',
- 'authorization logic',
- 'payment processing',
- 'user data handling',
- 'API endpoint creation',
- 'file upload handling',
- 'database queries',
- 'external API integration',
- ],
- skipWhen: [
- 'read-only operations on public data',
- 'internal development tooling',
- 'static documentation',
- 'styling changes',
- ],
- commands: [
- {
- name: 'Full Security Scan',
- description: 'Run comprehensive security analysis on the codebase',
- command: 'npx @claude-flow/cli security scan --depth full',
- example: 'npx @claude-flow/cli security scan --depth full --output security-report.json',
- },
- {
- name: 'Input Validation Check',
- description: 'Check for input validation issues',
- command: 'npx @claude-flow/cli security scan --check input-validation',
- example: 'npx @claude-flow/cli security scan --check input-validation --path ./src/api',
- },
- {
- name: 'Path Traversal Check',
- description: 'Check for path traversal vulnerabilities',
- command: 'npx @claude-flow/cli security scan --check path-traversal',
- },
- {
- name: 'SQL Injection Check',
- description: 'Check for SQL injection vulnerabilities',
- command: 'npx @claude-flow/cli security scan --check sql-injection',
- },
- {
- name: 'XSS Check',
- description: 'Check for cross-site scripting vulnerabilities',
- command: 'npx @claude-flow/cli security scan --check xss',
- },
- {
- name: 'CVE Scan',
- description: 'Scan dependencies for known CVEs',
- command: 'npx @claude-flow/cli security cve --scan',
- example: 'npx @claude-flow/cli security cve --scan --severity high',
- },
- {
- name: 'Security Audit Report',
- description: 'Generate full security audit report',
- command: 'npx @claude-flow/cli security audit --report',
- example: 'npx @claude-flow/cli security audit --report --format markdown --output SECURITY.md',
- },
- {
- name: 'Threat Modeling',
- description: 'Run threat modeling analysis',
- command: 'npx @claude-flow/cli security threats --analyze',
- },
- {
- name: 'Validate Secrets',
- description: 'Check for hardcoded secrets',
- command: 'npx @claude-flow/cli security validate --check secrets',
- },
- ],
- scripts: [
- {
- name: 'security-scan',
- path: '.agents/scripts/security-scan.sh',
- description: 'Run full security scan pipeline',
- },
- {
- name: 'cve-remediate',
- path: '.agents/scripts/cve-remediate.sh',
- description: 'Auto-remediate known CVEs',
- },
- ],
- references: [
- {
- name: 'Security Checklist',
- path: 'docs/security-checklist.md',
- description: 'Security review checklist',
- },
- {
- name: 'OWASP Guide',
- path: 'docs/owasp-top10.md',
- description: 'OWASP Top 10 mitigation guide',
- },
- ],
- },
- 'performance-analysis': {
- name: 'performance-analysis',
- description: 'Performance profiling, benchmarking, and optimization. Includes CPU profiling, memory analysis, latency measurement, and automated optimization suggestions.',
- triggers: [
- 'slow operations detected',
- 'memory usage issues',
- 'optimization needed',
- 'pre-release performance validation',
- 'database query optimization',
- 'API latency concerns',
- 'bundle size analysis',
- ],
- skipWhen: [
- 'early feature development',
- 'documentation updates',
- 'prototyping phase',
- 'configuration changes',
- ],
- commands: [
- {
- name: 'Run Benchmark Suite',
- description: 'Execute all performance benchmarks',
- command: 'npx @claude-flow/cli performance benchmark --suite all',
- example: 'npx @claude-flow/cli performance benchmark --suite all --iterations 100 --output bench-results.json',
- },
- {
- name: 'Profile Code',
- description: 'Profile code execution for CPU and memory',
- command: 'npx @claude-flow/cli performance profile --target ./src',
- example: 'npx @claude-flow/cli performance profile --target ./src/api --duration 60s',
- },
- {
- name: 'Memory Analysis',
- description: 'Analyze memory usage patterns',
- command: 'npx @claude-flow/cli performance metrics --metric memory',
- example: 'npx @claude-flow/cli performance metrics --metric memory --threshold 100MB',
- },
- {
- name: 'Latency Analysis',
- description: 'Measure and analyze latency',
- command: 'npx @claude-flow/cli performance metrics --metric latency',
- },
- {
- name: 'Optimize Suggestions',
- description: 'Get automated optimization suggestions',
- command: 'npx @claude-flow/cli performance optimize --analyze',
- example: 'npx @claude-flow/cli performance optimize --analyze --apply-safe',
- },
- {
- name: 'Performance Report',
- description: 'Generate performance report',
- command: 'npx @claude-flow/cli performance report',
- example: 'npx @claude-flow/cli performance report --format html --output perf-report.html',
- },
- {
- name: 'Compare Benchmarks',
- description: 'Compare benchmark results',
- command: 'npx @claude-flow/cli performance benchmark --compare baseline.json current.json',
- },
- {
- name: 'WASM Benchmark',
- description: 'Run WASM-specific benchmarks',
- command: 'npx @claude-flow/cli performance benchmark --suite wasm',
- },
- ],
- scripts: [
- {
- name: 'perf-baseline',
- path: '.agents/scripts/perf-baseline.sh',
- description: 'Capture performance baseline',
- },
- {
- name: 'perf-regression',
- path: '.agents/scripts/perf-regression.sh',
- description: 'Check for performance regressions',
- },
- ],
- references: [
- {
- name: 'Performance Guide',
- path: 'docs/performance.md',
- description: 'Performance optimization guide',
- },
- {
- name: 'Benchmark Reference',
- path: 'docs/benchmarks.md',
- description: 'Benchmark configuration reference',
- },
- ],
- },
- 'github-automation': {
- name: 'github-automation',
- description: 'GitHub workflow automation including PR management, CI/CD, issue tracking, and release management. Integrates with GitHub CLI for seamless automation.',
- triggers: [
- 'creating pull requests',
- 'setting up CI/CD pipelines',
- 'release management',
- 'issue tracking automation',
- 'branch management',
- 'code review workflows',
- 'repository maintenance',
- ],
- skipWhen: [
- 'local-only development',
- 'prototyping without commits',
- 'non-GitHub repositories',
- 'offline work',
- ],
- commands: [
- {
- name: 'Create Pull Request',
- description: 'Create a new pull request with summary',
- command: 'gh pr create --title "[title]" --body "[description]"',
- example: 'gh pr create --title "feat: add OAuth2 authentication" --body "## Summary\\n- Implemented OAuth2 flow\\n- Added token refresh\\n\\n## Test Plan\\n- Run auth tests"',
- },
- {
- name: 'View PR',
- description: 'View pull request details',
- command: 'gh pr view [number]',
- example: 'gh pr view 123 --comments',
- },
- {
- name: 'Merge PR',
- description: 'Merge a pull request',
- command: 'gh pr merge [number] --squash',
- example: 'gh pr merge 123 --squash --delete-branch',
- },
- {
- name: 'Run Workflow',
- description: 'Trigger a GitHub Actions workflow',
- command: 'gh workflow run [workflow]',
- example: 'gh workflow run ci.yml --ref feature-branch',
- },
- {
- name: 'View Workflow Runs',
- description: 'List recent workflow runs',
- command: 'gh run list --limit 10',
- },
- {
- name: 'Create Issue',
- description: 'Create a new issue',
- command: 'gh issue create --title "[title]" --body "[body]"',
- example: 'gh issue create --title "Bug: login fails on mobile" --body "## Description\\n..." --label bug',
- },
- {
- name: 'Create Release',
- description: 'Create a new release',
- command: 'gh release create [tag] --notes "[notes]"',
- example: 'gh release create v1.0.0 --notes "Initial release" --generate-notes',
- },
- {
- name: 'View Checks',
- description: 'View PR check status',
- command: 'gh pr checks [number]',
- example: 'gh pr checks 123 --watch',
- },
- {
- name: 'Review PR',
- description: 'Submit a PR review',
- command: 'gh pr review [number] --approve --body "[comment]"',
- example: 'gh pr review 123 --approve --body "LGTM! Great work on the tests."',
- },
- ],
- scripts: [
- {
- name: 'pr-template',
- path: '.agents/scripts/pr-template.sh',
- description: 'Generate PR from template',
- },
- {
- name: 'release-prep',
- path: '.agents/scripts/release-prep.sh',
- description: 'Prepare release with changelog',
- },
- ],
- references: [
- {
- name: 'GitHub CLI Reference',
- path: 'docs/gh-cli.md',
- description: 'GitHub CLI command reference',
- },
- {
- name: 'PR Guidelines',
- path: 'docs/pr-guidelines.md',
- description: 'Pull request best practices',
- },
- {
- name: 'CI/CD Setup',
- path: 'docs/ci-cd.md',
- description: 'CI/CD pipeline configuration',
- },
- ],
- },
- };
-
- const template = skillTemplates[skillName];
- if (!template) {
+ if (!BUILT_IN_SKILL_NAMES.includes(skillName as BuiltInSkill)) {
throw new Error(`Unknown built-in skill: ${skillName}`);
}
- const skillMd = await generateSkillMd(template);
-
- // Generate helper scripts
- const scripts: Record<string, string> = {};
- if (template.scripts) {
- for (const script of template.scripts) {
- // Use just the script filename, not the full path
- const scriptFilename = `${script.name}.sh`;
- scripts[scriptFilename] = generateHelperScript(skillName, script.name);
+ const skillRoot = path.join(BUILT_IN_SKILLS_ROOT, skillName);
+ let skillMd: string;
+ try {
+ skillMd = await readFile(path.join(skillRoot, 'SKILL.md'), 'utf8');
+ } catch (error) {
+ if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
+ throw new Error(`Built-in skill payload missing: ${skillName}/SKILL.md`);
}
+ throw error;
}
- return {
+ const result = {
skillMd,
- scripts,
- references: {},
+ scripts: await readPayloadTree(path.join(skillRoot, 'scripts')),
+ references: await readPayloadTree(path.join(skillRoot, 'references')),
};
+ validateBuiltInSkillPayload(skillName, result.skillMd, result.scripts, result.references);
+ return result;
}
/**
- * Generate a helper script for a skill
+ * Ensure every skill-local path is contained in and shipped with its tree.
*/
-function generateHelperScript(skillName: string, scriptName: string): string {
- const scripts: Record<string, Record<string, string>> = {
- 'swarm-orchestration': {
- 'swarm-start': `#!/bin/bash
-# Swarm Orchestration - Start Script
-# Initialize swarm with default anti-drift settings
-
-set -e
-
-echo "Initializing hierarchical swarm..."
-npx ruflo swarm init \\
- --topology hierarchical \\
- --max-agents 8 \\
- --strategy specialized
-
-echo "Swarm initialized successfully"
-npx @claude-flow/cli swarm status
-`,
- 'swarm-monitor': `#!/bin/bash
-# Swarm Orchestration - Monitor Script
-# Real-time swarm monitoring
-
-set -e
-
-echo "Starting swarm monitor..."
-npx @claude-flow/cli swarm status --watch --interval 5
-`,
- },
- 'memory-management': {
- 'memory-backup': `#!/bin/bash
-# Memory Management - Backup Script
-# Export memory to backup file
-
-set -e
-
-BACKUP_DIR="\${BACKUP_DIR:-./.backups}"
-TIMESTAMP=$(date +%Y%m%d_%H%M%S)
-BACKUP_FILE="\${BACKUP_DIR}/memory_\${TIMESTAMP}.json"
-
-mkdir -p "$BACKUP_DIR"
-
-echo "Backing up memory to $BACKUP_FILE..."
-npx @claude-flow/cli memory export --output "$BACKUP_FILE"
-
-echo "Backup complete: $BACKUP_FILE"
-`,
- 'memory-consolidate': `#!/bin/bash
-# Memory Management - Consolidate Script
-# Optimize and consolidate memory
-
-set -e
-
-echo "Running memory consolidation..."
-npx @claude-flow/cli hooks worker dispatch --trigger consolidate
-
-echo "Memory consolidation complete"
-npx @claude-flow/cli memory stats
-`,
- },
- 'sparc-methodology': {
- 'sparc-init': `#!/bin/bash
-# SPARC Methodology - Init Script
-# Initialize SPARC workflow for a new feature
-
-set -e
-
-FEATURE_NAME="\${1:-new-feature}"
-
-echo "Initializing SPARC workflow for: $FEATURE_NAME"
-
-# Create SPARC documentation directory
-mkdir -p "./docs/sparc/$FEATURE_NAME"
-
-# Create phase files
-touch "./docs/sparc/$FEATURE_NAME/1-specification.md"
-touch "./docs/sparc/$FEATURE_NAME/2-pseudocode.md"
-touch "./docs/sparc/$FEATURE_NAME/3-architecture.md"
-touch "./docs/sparc/$FEATURE_NAME/4-refinement.md"
-touch "./docs/sparc/$FEATURE_NAME/5-completion.md"
-
-echo "SPARC workflow initialized in ./docs/sparc/$FEATURE_NAME"
-`,
- 'sparc-review': `#!/bin/bash
-# SPARC Methodology - Review Script
-# Run SPARC phase review checklist
-
-set -e
-
-FEATURE_DIR="\${1:-.}"
-
-echo "SPARC Phase Review Checklist"
-echo "============================="
-
-for phase in specification pseudocode architecture refinement completion; do
- if [ -f "$FEATURE_DIR/\${phase}.md" ]; then
- echo "[x] $phase - found"
- else
- echo "[ ] $phase - missing"
- fi
-done
-`,
- },
- 'security-audit': {
- 'security-scan': `#!/bin/bash
-# Security Audit - Full Scan Script
-# Run comprehensive security scan pipeline
-
-set -e
-
-echo "Running full security scan..."
-
-# Input validation
-echo "Checking input validation..."
-npx @claude-flow/cli security scan --check input-validation
-
-# Path traversal
-echo "Checking path traversal..."
-npx @claude-flow/cli security scan --check path-traversal
-
-# SQL injection
-echo "Checking SQL injection..."
-npx @claude-flow/cli security scan --check sql-injection
-
-# XSS
-echo "Checking XSS..."
-npx @claude-flow/cli security scan --check xss
-
-# Secrets
-echo "Checking for hardcoded secrets..."
-npx @claude-flow/cli security validate --check secrets
-
-# CVE scan
-echo "Scanning dependencies for CVEs..."
-npx @claude-flow/cli security cve --scan
-
-echo "Security scan complete"
-`,
- 'cve-remediate': `#!/bin/bash
-# Security Audit - CVE Remediation Script
-# Auto-remediate known CVEs
-
-set -e
-
-echo "Scanning for CVEs..."
-npx @claude-flow/cli security cve --scan --severity high
-
-echo "Attempting auto-remediation..."
-npm audit fix
-
-echo "Re-scanning after remediation..."
-npx @claude-flow/cli security cve --scan
-
-echo "CVE remediation complete"
-`,
- },
- 'performance-analysis': {
- 'perf-baseline': `#!/bin/bash
-# Performance Analysis - Baseline Script
-# Capture performance baseline
-
-set -e
-
-BASELINE_FILE="\${1:-baseline.json}"
-
-echo "Capturing performance baseline..."
-npx @claude-flow/cli performance benchmark \\
- --suite all \\
- --iterations 100 \\
- --output "$BASELINE_FILE"
-
-echo "Baseline saved to $BASELINE_FILE"
-`,
- 'perf-regression': `#!/bin/bash
-# Performance Analysis - Regression Check Script
-# Check for performance regressions
-
-set -e
-
-BASELINE_FILE="\${1:-baseline.json}"
-CURRENT_FILE="current.json"
-THRESHOLD="\${2:-10}"
-
-echo "Running current benchmarks..."
-npx @claude-flow/cli performance benchmark \\
- --suite all \\
- --iterations 100 \\
- --output "$CURRENT_FILE"
-
-echo "Comparing against baseline..."
-npx @claude-flow/cli performance benchmark \\
- --compare "$BASELINE_FILE" "$CURRENT_FILE" \\
- --threshold "$THRESHOLD"
-
-rm "$CURRENT_FILE"
-`,
- },
- 'github-automation': {
- 'pr-template': `#!/bin/bash
-# GitHub Automation - PR Template Script
-# Generate PR from template
-
-set -e
-
-TITLE="\${1:-Update}"
-BRANCH=$(git rev-parse --abbrev-ref HEAD)
-
-echo "Creating PR for branch: $BRANCH"
-
-gh pr create \\
- --title "$TITLE" \\
- --body "$(cat <<EOF
-## Summary
-<!-- Describe your changes -->
-
-## Test Plan
-- [ ] Unit tests pass
-- [ ] Integration tests pass
-- [ ] Manual testing completed
-
-## Checklist
-- [ ] Code follows style guidelines
-- [ ] Documentation updated
-- [ ] No breaking changes
-
-Generated with claude-flow
-EOF
-)"
-
-echo "PR created successfully"
-`,
- 'release-prep': `#!/bin/bash
-# GitHub Automation - Release Prep Script
-# Prepare release with changelog
-
-set -e
-
-VERSION="\${1:-patch}"
-
-echo "Preparing release..."
-
-# Bump version
-npm version "$VERSION" --no-git-tag-version
-
-NEW_VERSION=$(node -p "require('./package.json').version")
-
-echo "Creating release v$NEW_VERSION..."
-gh release create "v$NEW_VERSION" \\
- --generate-notes \\
- --draft
-
-echo "Draft release v$NEW_VERSION created"
-`,
- },
- };
+export function validateBuiltInSkillPayload(
+ skillName: string,
+ skillMd: string,
+ scripts: Record<string, string>,
+ references: Record<string, string>,
+): void {
+ const localPaths = Array.from(
+ skillMd.matchAll(/`((?:scripts|references)\/[^`\s]+)`/g),
+ (match) => match[1]!,
+ );
- const skillScripts = scripts[skillName];
- if (skillScripts && skillScripts[scriptName]) {
- return skillScripts[scriptName];
+ for (const localPath of localPaths) {
+ const normalized = path.posix.normalize(localPath.replaceAll('\\', '/'));
+ if (normalized.startsWith('../') || path.posix.isAbsolute(normalized)) {
+ throw new Error(`Built-in skill path escapes ${skillName}: ${localPath}`);
+ }
+ const slash = normalized.indexOf('/');
+ const directory = normalized.slice(0, slash);
+ const payloadPath = normalized.slice(slash + 1);
+ const payload = directory === 'scripts' ? scripts : references;
+ if (!Object.hasOwn(payload, payloadPath)) {
+ throw new Error(`Built-in skill payload missing: ${skillName}/${normalized}`);
+ }
}
-
- return `#!/bin/bash
-# ${skillName} - ${scriptName}
-# Generated by @claude-flow/codex
-
-set -e
-
-echo "Running ${scriptName}..."
-# Add your script logic here
-`;
}
diff --git a/v3/@claude-flow/codex/src/initializer.ts b/v3/@claude-flow/codex/src/initializer.ts
index b2fbb91546..c9c13be86c 100644
--- a/v3/@claude-flow/codex/src/initializer.ts
+++ b/v3/@claude-flow/codex/src/initializer.ts
@@ -14,7 +14,11 @@ import type {
BuiltInSkill,
} from './types.js';
import { generateAgentsMd } from './generators/agents-md.js';
-import { generateSkillMd, generateBuiltInSkill } from './generators/skill-md.js';
+import {
+ BUILT_IN_SKILL_NAMES,
+ generateSkillMd,
+ generateBuiltInSkill,
+} from './generators/skill-md.js';
import { generateConfigToml } from './generators/config-toml.js';
import { DEFAULT_SKILLS_BY_TEMPLATE, AGENTS_OVERRIDE_TEMPLATE, GITIGNORE_ENTRIES, ALL_AVAILABLE_SKILLS } from './templates/index.js';
import { getRufloMcpAddCommand } from './mcp-config.js';
@@ -555,18 +559,9 @@ web_search = "live"
await fs.ensureDir(skillDir);
// Check if it's a built-in skill
- const builtInSkills: BuiltInSkill[] = [
- 'swarm-orchestration',
- 'memory-management',
- 'sparc-methodology',
- 'security-audit',
- 'performance-analysis',
- 'github-automation',
- ];
-
let skillMd: string;
- if (builtInSkills.includes(skillName as BuiltInSkill)) {
+ if (BUILT_IN_SKILL_NAMES.includes(skillName as BuiltInSkill)) {
const result = await generateBuiltInSkill(skillName);
skillMd = result.skillMd;
@@ -575,15 +570,19 @@ web_search = "live"
const scriptsDir = path.join(skillDir, 'scripts');
await fs.ensureDir(scriptsDir);
for (const [scriptName, scriptContent] of Object.entries(result.scripts)) {
- await fs.writeFile(path.join(scriptsDir, scriptName), scriptContent, 'utf-8');
+ const scriptPath = path.join(scriptsDir, scriptName);
+ await fs.ensureDir(path.dirname(scriptPath));
+ await fs.writeFile(scriptPath, scriptContent, 'utf-8');
}
}
if (Object.keys(result.references).length > 0) {
- const refsDir = path.join(skillDir, 'docs');
+ const refsDir = path.join(skillDir, 'references');
await fs.ensureDir(refsDir);
for (const [refName, refContent] of Object.entries(result.references)) {
- await fs.writeFile(path.join(refsDir, refName), refContent, 'utf-8');
+ const referencePath = path.join(refsDir, refName);
+ await fs.ensureDir(path.dirname(referencePath));
+ await fs.writeFile(referencePath, refContent, 'utf-8');
}
}
} else {
diff --git a/v3/@claude-flow/codex/tests/dual-mode.test.ts b/v3/@claude-flow/codex/tests/dual-mode.test.ts
index 2f4167fc89..5b7992e31b 100644
--- a/v3/@claude-flow/codex/tests/dual-mode.test.ts
+++ b/v3/@claude-flow/codex/tests/dual-mode.test.ts
@@ -9,7 +9,11 @@ import { describe, it, expect } from 'vitest';
import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs';
import { tmpdir } from 'node:os';
import { join } from 'node:path';
-import { parseWorkerSpecs, createDualModeCommand } from '../src/dual-mode/cli.js';
+import {
+ parseWorkerSpecs,
+ createDualModeCommand,
+ loadWorkerConfig,
+} from '../src/dual-mode/cli.js';
import {
DualModeOrchestrator,
CollaborationTemplates,
@@ -68,6 +72,26 @@ describe('parseWorkerSpecs', () => {
});
});
+describe('loadWorkerConfig', () => {
+ it('loads a relative JSON config without import assertions (#2766)', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ruflo-dual-config-'));
+ writeFileSync(join(root, 'workers.json'), JSON.stringify({
+ taskContext: 'JSON collaboration',
+ workers: [{ id: 'reader', platform: 'codex', role: 'reader', prompt: 'inspect' }],
+ }));
+ await expect(loadWorkerConfig('workers.json', root)).resolves.toMatchObject({
+ taskContext: 'JSON collaboration',
+ workers: [{ id: 'reader', platform: 'codex' }],
+ });
+ });
+
+ it('rejects configs without a workers array', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'ruflo-dual-config-invalid-'));
+ writeFileSync(join(root, 'workers.json'), '{}');
+ await expect(loadWorkerConfig('workers.json', root)).rejects.toThrow('workers array');
+ });
+});
+
describe('CollaborationTemplates', () => {
it('featureDevelopment: architect -> coder -> tester -> reviewer', () => {
const ws = CollaborationTemplates.featureDevelopment('Add OAuth');
@@ -175,6 +199,45 @@ describe('DualModeOrchestrator', () => {
expect(o.config.claudeCommand).toBe('claude');
expect(o.config.maxConcurrent).toBe(4);
expect(o.config.sharedNamespace).toBe('collaboration');
+ expect(o.config.memoryDbPath).toBe('/tmp/.claude-flow/dual-mode-memory.db');
+ });
+
+ it('pins bootstrap and workers to one shared memory database (#2766)', () => {
+ const root = mkdtempSync(join(tmpdir(), 'ruflo-dual-memory-'));
+ const memoryDbPath = join(root, 'state', 'shared.db');
+ const orchestrator = new DualModeOrchestrator({
+ projectPath: root,
+ memoryDbPath,
+ }) as unknown as {
+ sharedEnvironment(): NodeJS.ProcessEnv;
+ workerEnvironment(worker: WorkerConfig): NodeJS.ProcessEnv;
+ };
+ const worker: WorkerConfig = {
+ id: 'memory-worker',
+ platform: 'codex',
+ role: 'researcher',
+ prompt: 'search memory',
+ readOnly: true,
+ };
+
+ expect(orchestrator.sharedEnvironment().CLAUDE_FLOW_DB_PATH).toBe(memoryDbPath);
+ expect(orchestrator.workerEnvironment(worker).CLAUDE_FLOW_DB_PATH).toBe(memoryDbPath);
+ });
+
+ it('preserves an existing CLAUDE_FLOW_DB_PATH by default', () => {
+ const previous = process.env.CLAUDE_FLOW_DB_PATH;
+ const root = mkdtempSync(join(tmpdir(), 'ruflo-dual-memory-env-'));
+ const configured = join(root, 'existing.db');
+ process.env.CLAUDE_FLOW_DB_PATH = configured;
+ try {
+ const orchestrator = new DualModeOrchestrator({ projectPath: root }) as unknown as {
+ config: { memoryDbPath: string };
+ };
+ expect(orchestrator.config.memoryDbPath).toBe(configured);
+ } finally {
+ if (previous === undefined) delete process.env.CLAUDE_FLOW_DB_PATH;
+ else process.env.CLAUDE_FLOW_DB_PATH = previous;
+ }
});
it('does not pass policy or provider secrets to workers', () => {
diff --git a/v3/@claude-flow/codex/tests/generators.test.ts b/v3/@claude-flow/codex/tests/generators.test.ts
index 8fe00c98b6..2c1af4ee5c 100644
--- a/v3/@claude-flow/codex/tests/generators.test.ts
+++ b/v3/@claude-flow/codex/tests/generators.test.ts
@@ -11,13 +11,18 @@ import {
generateSkillMd,
generateConfigToml,
} from '../src/generators/index.js';
-import { generateBuiltInSkill } from '../src/generators/skill-md.js';
+import {
+ BUILT_IN_SKILL_NAMES,
+ generateBuiltInSkill,
+ validateBuiltInSkillPayload,
+} from '../src/generators/skill-md.js';
import {
generateMinimalConfigToml,
generateCIConfigToml,
} from '../src/generators/config-toml.js';
import { resolveBundledSkillsPath } from '../src/initializer.js';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
import type {
AgentsMdOptions,
SkillMdOptions,
@@ -567,7 +572,7 @@ describe('generateBuiltInSkill', () => {
expect(result.skillMd).toContain('name: swarm-orchestration');
expect(result.skillMd).toContain('Multi-agent swarm coordination');
expect(result.skillMd).toContain('Initialize Swarm');
- expect(result.skillMd).toContain('npx ruflo swarm init');
+ expect(result.skillMd).toContain('npx @claude-flow/cli swarm init');
});
it('should generate memory-management skill', async () => {
@@ -575,8 +580,8 @@ describe('generateBuiltInSkill', () => {
expect(result.skillMd).toContain('name: memory-management');
expect(result.skillMd).toContain('AgentDB memory system');
- expect(result.skillMd).toContain('Store Pattern');
- expect(result.skillMd).toContain('Semantic Search');
+ expect(result.skillMd).toContain('Store Data');
+ expect(result.skillMd).toContain('Search Data');
});
it('should generate sparc-methodology skill', async () => {
@@ -592,7 +597,7 @@ describe('generateBuiltInSkill', () => {
const result = await generateBuiltInSkill('security-audit');
expect(result.skillMd).toContain('name: security-audit');
- expect(result.skillMd).toContain('security scanning');
+ expect(result.skillMd).toContain('Security scanning');
expect(result.skillMd).toContain('Full Security Scan');
expect(result.skillMd).toContain('--depth full');
});
@@ -621,21 +626,48 @@ describe('generateBuiltInSkill', () => {
);
});
- it('should return generated scripts for skills with scripts', async () => {
- const result = await generateBuiltInSkill('swarm-orchestration');
-
- // Scripts are now generated for skills that have them
- expect(Object.keys(result.scripts).length).toBeGreaterThan(0);
- expect(result.references).toEqual({});
+ it('uses packaged skill trees as the canonical generator source (#2765)', async () => {
+ const bundledRoot = resolveBundledSkillsPath();
+ for (const skillName of BUILT_IN_SKILL_NAMES) {
+ const result = await generateBuiltInSkill(skillName);
+ const packaged = readFileSync(join(bundledRoot, skillName, 'SKILL.md'), 'utf8');
+ expect(result.skillMd).toBe(packaged);
+ }
});
- it('should generate valid bash scripts', async () => {
- const result = await generateBuiltInSkill('memory-management');
-
- // Check that scripts are generated and contain bash shebang
- for (const script of Object.values(result.scripts)) {
- expect(script).toContain('#!/bin/bash');
- expect(script).toContain('set -e');
+ it('ships every local path and prevents paths escaping the skill root', async () => {
+ for (const skillName of BUILT_IN_SKILL_NAMES) {
+ const result = await generateBuiltInSkill(skillName);
+ expect(() => validateBuiltInSkillPayload(
+ skillName,
+ result.skillMd,
+ result.scripts,
+ result.references,
+ )).not.toThrow();
+ }
+ expect(() => validateBuiltInSkillPayload(
+ 'broken-skill',
+ 'Use `scripts/missing.sh`.',
+ {},
+ {},
+ )).toThrow('broken-skill/scripts/missing.sh');
+ expect(() => validateBuiltInSkillPayload(
+ 'escaping-skill',
+ 'Use `scripts/../../outside.sh`.',
+ {},
+ {},
+ )).toThrow('escapes escaping-skill');
+ });
+
+ it('packages all canonical built-in skill trees in npm artifacts', () => {
+ const bundledRoot = resolveBundledSkillsPath();
+ const packageJson = JSON.parse(readFileSync(
+ join(bundledRoot, '..', '..', 'package.json'),
+ 'utf8',
+ )) as { files: string[] };
+ expect(packageJson.files).toContain('.agents/skills');
+ for (const skillName of BUILT_IN_SKILL_NAMES) {
+ expect(existsSync(join(bundledRoot, skillName, 'SKILL.md'))).toBe(true);
}
});
});
diff --git a/v3/docs/adr/ADR-103-witness-temporal-history.md b/v3/docs/adr/ADR-103-witness-temporal-history.md
index 647462294e..2bc83c8cae 100644
--- a/v3/docs/adr/ADR-103-witness-temporal-history.md
+++ b/v3/docs/adr/ADR-103-witness-temporal-history.md
@@ -3,7 +3,7 @@
**Status**: Accepted
**Date**: 2026-05-08
**Version**: [email protected]+ / @claude-flow/[email protected]+
-**Related**: ADR-102 (CI smoke harness), #1867, #1859, #1862, project memory `project_verification_process.md`
+**Related**: ADR-102 (CI smoke harness), ADR-332 (hermetic source verification), #1867, #1859, #1862, project memory `project_verification_process.md`
## Context
@@ -87,8 +87,10 @@ Plus exposure as Claude Code surface area:
| `plugins/ruflo-core/agents/witness-curator.md` | Agent for adding fixes / interpreting regressions |
The scripts are project-agnostic: they take `--manifest`, `--history`,
-`--fixes`, `--root` flags. They probe `<root>` and `<root>/v3` for
-`@noble/ed25519`, so they work in monorepo and flat layouts.
+`--fixes`, `--root` flags. Manifest generation probes `<root>` and
+`<root>/v3` for `@noble/ed25519`, so it works in monorepo and flat layouts.
+As amended by ADR-332, verification uses `node:crypto` and needs no installed
+package; `--source-only` authenticates clean source checkouts explicitly.
The ruflo internal entrypoint at `scripts/regen-witness.mjs` is now a
thin wrapper that hard-codes ruflo's paths and reads the
@@ -124,8 +126,9 @@ to a small set of commits to read.
per-fix lookups O(1) without scanning, which matters once history
reaches 100+ entries.
- `verify.mjs` is parallel to the bundled `ruflo verify` command but
- has no ruflo CLI dependency β€” adopters who only want the witness
- toolkit can install one tiny package (`@noble/ed25519`) and run it.
+ has no ruflo CLI or package dependency. Generation continues to use
+ `@noble/ed25519`; ADR-332 preserves its witness bytes while moving
+ standalone verification to Node's built-in Ed25519 implementation.
## Consequences
@@ -145,8 +148,9 @@ to a small set of commits to read.
- One extra file in the repo (`verification-history.jsonl`).
- ~2-3 KB per regen entry (81 fixes Γ— ~30 bytes avg). After 1000
regens, ~3 MB.
-- Adopters take a runtime dependency on `@noble/ed25519` (~15 KB
- minified, no transitive deps).
+- Adopters generating manifests take a development dependency on
+ `@noble/ed25519` (~15 KB minified, no transitive deps). Verification
+ itself has no package dependency (ADR-332).
### Not addressed (residual)
diff --git a/v3/docs/adr/ADR-174-memory-distillation-self-optimization.md b/v3/docs/adr/ADR-174-memory-distillation-self-optimization.md
index 31454bbca7..f67f80826b 100644
--- a/v3/docs/adr/ADR-174-memory-distillation-self-optimization.md
+++ b/v3/docs/adr/ADR-174-memory-distillation-self-optimization.md
@@ -26,7 +26,12 @@ Named `memory distill …` β€” deliberately **not** `neural distill …`, which
- **RETRIEVE** β€” reuse the embeddings already on every row (no re-embedding, $0).
- **JUDGE** β€” `feedback` entries are recorded post-edit outcomes = execution-observed ground truth β†’ `oracle:test-exec` tier. Everything else β†’ `proxy:structural`. (`judge:fable` is reserved for the explicitly opt-in, cost-bounded LLM path per ADR-172 β€” not enabled in the $0 default.)
- **DISTILL** β€” reuse the deterministic sub-millisecond extractor `structured-distill.ts` (`distillTrajectoryContent` β†’ `{summary, detail, labels, paths}`); greedily cluster near-duplicate entries by cosine distance so N near-identical logs collapse into one pattern with `uses` = cluster size.
-- **CONSOLIDATE** β€” write `episodes`, `reasoning_patterns`, `pattern_embeddings` (reusing the representative's existing vector as a Float32 BLOB; guaranteed **1:1** β€” a cluster with no parseable vector is skipped, never producing an embedding-less pattern), and **weak relational edges** (see below).
+- **CONSOLIDATE** β€” write `episodes`, `episode_embeddings`,
+ `reasoning_patterns`, and `pattern_embeddings` (reusing the representative's
+ existing vector as a Float32 BLOB; both episode and pattern coverage are
+ guaranteed **1:1** β€” a cluster with no parseable vector is skipped), plus
+ **weak relational edges** (see below). Execution-feedback episodes preserve
+ critique/error text; proxy episodes do not invent critiques.
- **Promote gate (ADR-171)** β€” a pattern is `promoted` only if its tier is `oracle:test-exec` (or `judge:fable`). `proxy:structural` patterns are written but **never** promoted β€” visible for audit, excluded from promoted recall. Enforced in code, not just prose.
### Relational edges are NOT causal proof (high-risk naming)
@@ -45,7 +50,9 @@ promoted = false
### Safety (the DB was just recovered from corruption)
- **Incremental** via a `distill_state` cursor (per namespace, by monotonic `rowid`) β€” never rescans processed rows.
-- **Non-destructive** β€” never mutates or deletes `memory_entries`; only inserts into the previously-empty target tables.
+- **Non-destructive source** β€” never mutates or deletes `memory_entries`.
+ Target-table repair may backfill missing `episode_embeddings` and feedback
+ critiques created by older distillation releases.
- **Transactional** per batch β€” a failure rolls back the batch and advances no cursor.
- **quick_check gate** before any write β€” skips (does not throw) on a corrupt DB, deferring to `recoverMemoryDatabase`.
- **better-sqlite3 optional** β€” silent no-op if the native module is absent (WASM-only hosts).
@@ -152,7 +159,12 @@ Governed memory consolidation with provenance, rollback, and no surprise model s
## Acceptance test
-Run distill **twice** on a copy of a production DB and require: `memory_entries` unchanged (count + content hash); the second run processes **0** rows; `proxy_promoted == 0`; `patterns_without_embeddings == 0`; and held-out MRR@10 no worse than baseline by more than 0.002. (Covered by `__tests__/memory-distillation.test.ts` + `distill-tuning.test.ts`.)
+Run distill **twice** on a copy of a production DB and require:
+`memory_entries` unchanged (count + content hash); the second run processes
+**0** rows; `proxy_promoted == 0`; `patterns_without_embeddings == 0`;
+`episodes_without_embeddings == 0`; execution-feedback critiques are non-empty;
+and held-out MRR@10 is no worse than baseline by more than 0.002. (Covered by
+`__tests__/memory-distillation.test.ts` + `distill-tuning.test.ts`.)
## Security β€” signed provenance for the helper auto-refresh
@@ -168,7 +180,12 @@ those helpers **auto-execute on every tool use**, the refresh is gated by
**GCP Secret Manager** (`RUFLO_HELPERS_SIGNING_SECRET=ruflo-helpers-signing-key`,
fetched via `gcloud secrets versions access`), with a local-PEM fallback
(`RUFLO_HELPERS_SIGNING_KEY`) for air-gapped signing. It is **never committed**.
+- Windows selects `gcloud.cmd`; a safe fallback accepts the key only through
+ piped stdin (`--stdin-key`), refuses interactive key entry, validates the
+ Ed25519 key type, and never echoes parser input.
- The public key is baked into `src/init/helper-signing.ts` (`RUFLO_HELPERS_PUBKEY`).
+ The prepublish verifier imports that compiled constant rather than carrying a
+ second rotation-sensitive copy.
- Before the refresh installs any helper, it verifies the manifest signature
against the baked key AND each source helper's SHA-256 against the manifest. A
tampered helper or manifest β€” e.g. a sibling package's `postinstall` overwriting
@@ -182,7 +199,10 @@ those helpers **auto-execute on every tool use**, the refresh is gated by
## Rollback
-Disable via `-w` omission or `--no-distill`. All writes are additive to the previously-empty target tables and never touch `memory_entries`, so full revert = stop the worker and optionally `DELETE FROM reasoning_patterns/pattern_embeddings/episodes/causal_edges` β€” zero data loss on the source.
+Disable via `-w` omission or `--no-distill`. Distillation never touches
+`memory_entries`, so full revert = stop the worker and optionally delete the
+derived `reasoning_patterns`, `pattern_embeddings`, `episodes`,
+`episode_embeddings`, and `causal_edges` rows β€” zero data loss on the source.
## Status of milestones
diff --git a/v3/docs/adr/ADR-332-hermetic-release-verification-runtime-baseline.md b/v3/docs/adr/ADR-332-hermetic-release-verification-runtime-baseline.md
new file mode 100644
index 0000000000..81c4b40961
--- /dev/null
+++ b/v3/docs/adr/ADR-332-hermetic-release-verification-runtime-baseline.md
@@ -0,0 +1,128 @@
+# ADR-332: Hermetic Release Verification and Supported Runtime Baseline
+
+**Status:** Accepted and implemented
+**Date:** 2026-07-29
+**Issues:** #2729, #2732, #2744, #2847
+**Related:** ADR-102, ADR-103, ADR-104, ADR-166
+
+## Context
+
+Release-security checks must produce useful evidence in both a built workspace
+and a clean source checkout. The standalone ADR-103 witness verifier previously
+required `@noble/ed25519` to be installed before it could authenticate a
+manifest. Its full-tree mode also required generated `dist/` files. A scheduled
+source-only check could therefore report an environmental precondition instead
+of checking the source markers it actually had.
+
+The two MCP bridge images also used Node 20 after that release line reached end
+of life. A green source test did not prevent the deployed image from retaining
+an unsupported runtime.
+
+Two related tracker reports describe release markers and transport exports that
+have since been implemented on `main`. An open issue is not, by itself,
+evidence that the defect is still present; remediation must be based on current
+source and executable checks.
+
+## Decision
+
+### 1. Verify witness signatures with the platform runtime
+
+`plugins/ruflo-core/scripts/witness/verify.mjs` uses Node's built-in
+`node:crypto` Ed25519 implementation. RFC 8410 PKCS#8 and SPKI wrappers convert
+the existing raw seed and public-key bytes without changing the signed witness
+format. Existing manifests produced with `@noble/ed25519` remain verifiable
+byte-for-byte.
+
+Verification checks three independent statements:
+
+1. the manifest body hashes to `integrity.manifestHash`;
+2. the deterministic key derived from the manifest commit reproduces
+ `integrity.publicKey`; and
+3. the Ed25519 signature authenticates the declared manifest hash.
+
+Malformed keys and signatures fail closed as verification errors. Verification
+does not download packages, inspect a global install, or silently substitute a
+different algorithm.
+
+### 2. Make source-only scope explicit
+
+`--source-only` authenticates the complete signed manifest, then checks every
+non-`dist/` marker available in a source checkout. Generated entries are not
+treated as verified: the JSON and human-readable results identify the
+`source-only` scope and report `skippedGenerated`.
+
+A source marker that is missing or regressed exits 1. An invalid signature
+exits 1. A manifest with no source entries exits 2 rather than succeeding
+vacuously.
+
+The existing no-flag behavior remains full-tree verification. If only generated
+artifacts are unavailable, it retains the `dist-not-built` precondition and
+exit 2. This preserves compatibility for release jobs that require evidence
+over shipped build output while giving source-only automation a real security
+check.
+
+### 3. Pin deployed MCP bridges to a supported LTS line
+
+Both MCP bridge Dockerfiles use `node:24-slim`. The ADR-166 static security
+lock checks both files and fails if either leaves the Node 24 LTS line. Updating
+the runtime when its support window approaches expiry is an explicit reviewed
+change, not an incidental base-image drift.
+
+This decision does not raise the repository-wide `engines.node` minimum.
+Libraries may retain their existing compatibility contract; the stricter rule
+applies to production images owned by this repository.
+
+### 4. Resolve tracker state from current executable evidence
+
+- #2729 is a confirmed defect and is remediated by hermetic signature
+ verification plus explicit source-only scope.
+- #2847 is a confirmed defect and is remediated by the supported Docker
+ runtime plus the static lock.
+- #2732 is stale on current `main`: the `@claude-flow/cli-core` and
+ `@ruvector/rvf-wasm` markers are present in the package metadata and signed
+ manifests, and the marker-drift smoke passes.
+- #2744 is stale on current `main`: federation owns a guarded transport loader
+ with a local WebSocket fallback, and CI forbids an unguarded phantom
+ `agentic-flow/transport/loader` dependency.
+
+Tracker updates should attach the commit and command output that support these
+classifications. This ADR does not authorize automated issue closure.
+
+## Security invariants
+
+1. Source-only mode never claims generated artifacts were checked.
+2. A valid source marker cannot compensate for an invalid signature.
+3. A signature cannot compensate for a missing or regressed selected marker.
+4. Full-tree verification semantics and historical witness bytes remain
+ backward compatible.
+5. Both deployable bridge variants use the same supported runtime baseline.
+6. Network access and package installation are not prerequisites for witness
+ authentication.
+
+## Acceptance tests
+
+1. In an isolated directory with no `node_modules`, a genuine manifest and all
+ referenced source files pass `verify.mjs --source-only`.
+2. A one-byte signature mutation exits 1.
+3. Removing a selected source marker exits 1 and reports a regression.
+4. Full-tree verification in the same unbuilt checkout exits 2 with
+ `dist-not-built`.
+5. JSON output names the verification scope, built-in verifier, and number of
+ skipped generated entries.
+6. The ADR-166 source lock passes for both Node 24 bridge images and fails for
+ an unsupported base line.
+7. Witness marker-drift and federation transport smoke tests pass on current
+ `main`.
+
+## Consequences
+
+Source verification becomes useful in clean clones, scheduled audits, and
+downstream repositories without weakening release verification. Operators can
+distinguish authenticated source evidence from complete built-artifact
+evidence. The package dependency remains available to witness generation and
+other consumers, but verification no longer depends on its installation
+layout.
+
+The Docker runtime assertion is intentionally time-sensitive. Before Node 24
+reaches end of life, a reviewed ADR amendment or successor must update both
+images and their regression lock.
diff --git a/v3/docs/adr/README.md b/v3/docs/adr/README.md
index 3043b8d8b5..1cb27126b3 100644
--- a/v3/docs/adr/README.md
+++ b/v3/docs/adr/README.md
@@ -49,6 +49,7 @@ All ADRs are located in [`/v3/implementation/adrs/`](../../implementation/adrs/)
| [ADR-329](ADR-329-ruflo-capability-brain-mcp-guidance.md) | Ruflo Capability Brain for MCP Guidance | Accepted |
| [ADR-330](ADR-330-adaptive-pheromone-swarm-consensus.md) | Adaptive Pheromone Swarm Consensus | Accepted |
| [ADR-331](ADR-331-project-local-flywheel-anchors.md) | Project-Local Flywheel Evaluation Anchors | Accepted |
+| [ADR-332](ADR-332-hermetic-release-verification-runtime-baseline.md) | Hermetic Release Verification and Supported Runtime Baseline | Accepted |
## Summary Documents
diff --git a/v3/docs/releases/v3.32.36.md b/v3/docs/releases/v3.32.36.md
new file mode 100644
index 0000000000..e3c2305557
--- /dev/null
+++ b/v3/docs/releases/v3.32.36.md
@@ -0,0 +1,162 @@
+# Ruflo v3.32.36: Trustworthy Signals, Portable Codex Workflows
+
+Ruflo v3.32.36 makes the information an agent sees line up with what the
+runtime is actually doing. Embedding commands now disclose when they are using
+the deterministic mock fallback, routing metrics distinguish confidence from
+measured outcomes, swarm status reads canonical agent state, and learned
+patterns preserve the task description that caused them.
+
+The release also makes mixed Claude Code and Codex installations easier to
+operate. Codex receives a native read-only Ruflo status skill, dual-mode memory
+workers share one database path, large MCP catalogs can be filtered for
+small-context models, and project/plugin hook overlap is claimed exactly once.
+Hermetic witness verification and Node 24 MCP images strengthen the release
+path without adding a runtime dependency.
+
+## Install or upgrade
+
+```bash
+npm install --global [email protected]
+ruflo doctor
+```
+
+Existing projects remain compatible. The default MCP tool set is unchanged,
+legacy memory state remains readable, explicit database-path overrides are
+preserved, and mock embeddings remain available. The difference is that
+degraded or unmeasured states are now reported honestly instead of being
+presented as grounded semantic results or routing accuracy.
+
+## Use a smaller MCP catalog
+
+Keep the default full catalog:
+
+```bash
+ruflo mcp start
+```
+
+Or select only the capabilities a constrained model needs:
+
+```bash
+ruflo mcp start --tools memory,swarm,hooks
+```
+
+The equivalent environment form is useful in MCP host configuration:
+
+```bash
+CLAUDE_FLOW_MCP_TOOLS=memory,swarm,hooks ruflo mcp start
+```
+
+Selectors accept categories, tool-name prefixes, and exact tool names. Ruflo
+doctor now reports catalog/schema overhead so the selection can be measured.
+
+## Inspect grounded learning state
+
+```bash
+ruflo embeddings status
+ruflo hooks metrics
+ruflo swarm status
+ruflo doctor --component memory
+```
+
+`embeddings status` identifies the active backend and whether semantic claims
+are grounded. Hook metrics expose average confidence and observed outcome
+success separately. The memory doctor checks structural integrity, content and
+embedding coverage, Reflexion episode coverage, and feedback critiques.
+
+To populate or repair the derived reasoning tables from existing memory:
+
+```bash
+ruflo memory distill run
+ruflo memory distill status
+```
+
+Raw `memory_entries` and the SONA feed remain the operational write path.
+`reasoning_patterns`, episodes, embeddings, critiques, and causal edges are
+derived intelligence populated by distillation or the consolidate worker.
+
+## Codex and dual-mode projects
+
+After initialization, Codex can invoke the native `ruflo-status` skill without
+receiving Cursor-specific permission JSON. Dual-mode workers now use a shared
+`CLAUDE_FLOW_DB_PATH`, including worker subprocesses and relative configuration
+files, so bootstrap, writes, reads, policy checks, and background work observe
+the same database.
+
+The packaged Codex skill set now includes:
+
+- swarm orchestration;
+- memory management;
+- SPARC methodology;
+- security audit;
+- GitHub automation;
+- performance analysis.
+
+## Security and verification
+
+- Witness signature verification uses Node's built-in Ed25519 support in a
+ source-only checkout and preserves the legacy exit-2 precondition for an
+ unbuilt full-tree verification.
+- Helper signing has one public-key source, supports a piped stdin key, uses
+ `gcloud.cmd` on Windows, validates Ed25519 keys, and redacts failures.
+- MCP bridge images use the supported Node 24 LTS line.
+- MetaHarness wrappers preserve structured HIGH findings when the upstream
+ scanner exits non-zero.
+- Root and packaged hook helpers are byte-identical and covered by a signed
+ four-helper manifest.
+
+## What changed
+
+- Reports the actual embedding backend and suppresses unsupported semantic
+ interpretations while the mock fallback is active.
+- Replaces misleading β€œRouting Accuracy” output with average confidence and
+ measured outcome-success signals.
+- Fixes learned-pattern success/failure counts and retains task descriptions in
+ the learning write.
+- Reads canonical per-agent IDs and statuses for `agent list` and
+ `swarm status`.
+- Fixes statusline install discovery, numeric version comparison, project-root
+ resolution, and legacy nested-intelligence migration.
+- Keeps non-TTY spinner output clean and erases TTY spinner lines correctly.
+- Deduplicates overlapping project/plugin post-edit and session-end side
+ effects using an atomic event claim.
+- Adds MCP tool filtering and schema-overhead diagnostics.
+- Repairs dual-mode Codex memory-path consistency and packaged skill assets.
+- Adds memory distillation episode embeddings, historical backfill, critique
+ preservation, and strict doctor coverage checks.
+
+## Validation
+
+- All 23 V3 workspace packages built successfully.
+- 171 changed-surface CLI tests passed.
+- Codex passed 235 tests, security passed 559, and federation passed 640.
+- Ruflo core hook integration passed 22/22, including duplicate-event
+ exactly-once behavior.
+- MetaHarness passed its complete plugin regression matrix, including
+ structured finding preservation.
+- Helper signing security, hermetic witness, MCP security lock, scan-format,
+ and 37 release invariants passed.
+- The stable release workflow additionally installs and tests immutable tarball
+ archives for `@claude-flow/cli`, `claude-flow`, and `ruflo` before publishing
+ those exact bytes.
+
+This release resolves the current runtime and verification defects tracked in
+[#2847](https://github.com/ruvnet/ruflo/issues/2847),
+[#2821](https://github.com/ruvnet/ruflo/issues/2821),
+[#2818](https://github.com/ruvnet/ruflo/issues/2818),
+[#2816](https://github.com/ruvnet/ruflo/issues/2816),
+[#2814](https://github.com/ruvnet/ruflo/issues/2814),
+[#2812](https://github.com/ruvnet/ruflo/issues/2812),
+[#2811](https://github.com/ruvnet/ruflo/issues/2811),
+[#2810](https://github.com/ruvnet/ruflo/issues/2810),
+[#2809](https://github.com/ruvnet/ruflo/issues/2809),
+[#2808](https://github.com/ruvnet/ruflo/issues/2808),
+[#2807](https://github.com/ruvnet/ruflo/issues/2807),
+[#2805](https://github.com/ruvnet/ruflo/issues/2805),
+[#2766](https://github.com/ruvnet/ruflo/issues/2766),
+[#2765](https://github.com/ruvnet/ruflo/issues/2765),
+[#2750](https://github.com/ruvnet/ruflo/issues/2750),
+[#2729](https://github.com/ruvnet/ruflo/issues/2729),
+[#2726](https://github.com/ruvnet/ruflo/issues/2726),
+[#2677](https://github.com/ruvnet/ruflo/issues/2677),
+[#2675](https://github.com/ruvnet/ruflo/issues/2675), and
+[#2674](https://github.com/ruvnet/ruflo/issues/2674).