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

docs(mods): capability review 2026-10 and matrix generator

ruva98f66344fc8
diff --git a/scripts/__tests__/mod-capability-matrix.test.mjs b/scripts/__tests__/mod-capability-matrix.test.mjs
new file mode 100644
index 0000000000..ad2884ab82
--- /dev/null
+++ b/scripts/__tests__/mod-capability-matrix.test.mjs
@@ -0,0 +1,106 @@
+import assert from 'node:assert/strict'
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { after, before, describe, test } from 'node:test'
+
+import { buildMatrix, collisions, duplicateGroups, scanPlugin, testTitles } from '../mod-capability-matrix.mjs'
+
+let root
+
+/** Writes one fake plugin: manifest, hooks.json, hook sources and a test file. */
+function plugin(name, { version = '1.0.0', userConfig = {}, files = {}, modules = ['./register.ts'], tests = {} } = {}) {
+ const dir = join(root, name)
+ mkdirSync(join(dir, '.claude-plugin'), { recursive: true })
+ mkdirSync(join(dir, 'hooks'), { recursive: true })
+ mkdirSync(join(dir, 'tests'), { recursive: true })
+ writeFileSync(join(dir, '.claude-plugin', 'plugin.json'), JSON.stringify({ name, version, userConfig }))
+ writeFileSync(join(dir, 'hooks', 'hooks.json'), JSON.stringify(modules.length ? { modules } : {}))
+ for (const [f, text] of Object.entries(files)) writeFileSync(join(dir, 'hooks', f), text)
+ for (const [f, text] of Object.entries(tests)) writeFileSync(join(dir, 'tests', f), text)
+ return dir
+}
+
+before(() => {
+ root = mkdtempSync(join(tmpdir(), 'mod-matrix-'))
+})
+after(() => rmSync(root, { recursive: true, force: true }))
+
+describe('scanPlugin', () => {
+ test('reads version, userConfig defaults, events, commands and the status path from sources', () => {
+ const dir = plugin('alpha', {
+ version: '0.4.2',
+ userConfig: { guard: { type: 'boolean', default: true }, limit: { type: 'number' } },
+ files: {
+ 'register.ts': `on('session.start', async ($, e, next) => next(e))
+on('tool.call', async ($, e, next) => next(e))
+on('command.run', { command: 'alpha-mod' }, async () => ({ text: 'x' }))
+await $.command.register({ name: 'alpha-mod', description: 'd' })`,
+ 'status.ts': `export const STATUS_PATH = '.claude-flow/alpha-mod/status.json'`,
+ 'guard.ts': `const WATCHED = ['memory_store', 'mcp__ruflo__agentdb_hierarchical-store']`,
+ },
+ })
+ const row = scanPlugin(dir)
+ assert.equal(row.version, '0.4.2')
+ assert.equal(row.isMod, true)
+ assert.deepEqual(Object.keys(row.events).sort(), ['command.run', 'session.start', 'tool.call'])
+ assert.deepEqual(row.commands, { run: ['alpha-mod'], registered: ['alpha-mod'] })
+ assert.deepEqual(row.statusPaths, ['.claude-flow/alpha-mod/status.json'])
+ assert.deepEqual(row.guardTools, ['mcp__ruflo__agentdb_hierarchical-store', 'memory_store'])
+ assert.deepEqual(row.userConfig, { guard: { type: 'boolean', default: true }, limit: { type: 'number', default: null } })
+ assert.equal(row.classicFallback, false)
+ })
+
+ test('a status path that is only mentioned is a read, not a write', () => {
+ const dir = plugin('reader', { files: { 'register.ts': `const p = '.claude-flow/other-mod/status.json'` } })
+ const row = scanPlugin(dir)
+ assert.deepEqual(row.statusPaths, [])
+ assert.deepEqual(row.statusReads, ['.claude-flow/other-mod/status.json'])
+ })
+
+ test('a plugin with no modules is not a mod, and test files are not sources', () => {
+ const dir = plugin('classic', { modules: [], files: { 'x.test.ts': `on('tool.call', 1)` } })
+ const row = scanPlugin(dir)
+ assert.equal(row.isMod, false)
+ assert.deepEqual(row.events, {})
+ })
+})
+
+describe('testTitles', () => {
+ test('lists test and it titles, quotes of any kind', () => {
+ const dir = plugin('titled', { tests: { 'a.test.ts': `test('one', () => {})\nit("two", () => {})\ntest(\`three\`, () => {})\n// not a test(x)` } })
+ assert.deepEqual(testTitles(join(dir, 'tests', 'a.test.ts')), ['one', 'two', 'three'])
+ })
+})
+
+describe('collisions and duplicates', () => {
+ test('collisions keeps only names claimed by two or more plugins', () => {
+ assert.deepEqual(collisions({ a: ['x', 'y', 'x'], b: ['y'], c: ['z'] }), { y: ['a', 'b'] })
+ })
+
+ test('duplicateGroups puts identical copies together, largest first', () => {
+ for (const n of ['p1', 'p2', 'p3']) plugin(n, { files: { 'screen.ts': n === 'p3' ? 'drifted' : 'same' } })
+ const groups = duplicateGroups(root, ['p1', 'p2', 'p3'], 'screen.ts')
+ assert.deepEqual(groups.map((g) => g.plugins), [['p1', 'p2'], ['p3']])
+ })
+})
+
+describe('buildMatrix', () => {
+ test('skips dot directories, counts mods, and takes test counts only from the counts file', () => {
+ mkdirSync(join(root, '.claude-flow'), { recursive: true })
+ plugin('m1', { files: { 'register.ts': `on('tool.call', 1)` } })
+ plugin('plain', { modules: [] })
+ const m = buildMatrix(root, { m1: 7 })
+ assert.ok(!('.claude-flow' in m.plugins))
+ assert.equal(m.plugins.m1.testCount, 7)
+ assert.equal(m.plugins.plain.testCount, null)
+ assert.ok(m.summary.withoutMod.includes('plain'))
+ assert.equal(m.summary.pluginsWithToolCallHook >= 1, true)
+ assert.equal(m.schema, 1)
+ })
+
+ test('the real tree: every mod exports at least session.start', () => {
+ const m = buildMatrix(new URL('../../plugins', import.meta.url).pathname)
+ for (const [name, row] of Object.entries(m.plugins)) if (row.isMod) assert.ok(row.events['session.start'], `${name} has no session.start`)
+ })
+})
diff --git a/scripts/mod-capability-matrix.mjs b/scripts/mod-capability-matrix.mjs
new file mode 100644
index 0000000000..71161148a5
--- /dev/null
+++ b/scripts/mod-capability-matrix.mjs
@@ -0,0 +1,188 @@
+#!/usr/bin/env node
+/**
+ * Regenerates the machine-checkable half of the mod capability matrix
+ * (v3/docs/validation/mod-capability-review-2026-10.md) as JSON on stdout.
+ *
+ * node scripts/mod-capability-matrix.mjs [--plugins-dir plugins] [--counts counts.json]
+ *
+ * Reads only files: each plugin's .claude-plugin/plugin.json (version, userConfig keys and defaults),
+ * hooks/hooks.json (modules, classic fallback) and the hooks/*.ts sources (events, commands, status
+ * paths, guarded tool names). `--counts` is a JSON object `{ "<plugin>": <test count> }` measured by
+ * the caller (`claude plugin test` / vitest); without it every count is null, never a guess.
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs'
+import { join, relative, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** Files that the per-plugin mod generator copied; the groups are the copy-drift report. */
+export const SHARED_FILES = ['screen.ts', 'status.ts', 'command.ts', 'options.ts', 'guard.ts']
+
+const EVENT_RE = /\bon\(\s*'([a-z]+\.[a-z.]+)'/g
+const COMMAND_RUN_RE = /\bon\(\s*'command\.run'\s*,\s*\{\s*command:\s*'([^']+)'/g
+const COMMAND_REG_RE = /command\.register\(\s*\{\s*name:\s*'([^']+)'/g
+const STATUS_WRITE_RE = /STATUS_PATH\s*=\s*'([^']+)'/g
+const STATUS_ANY_RE = /'(\.claude-flow\/[a-z0-9-]+-mod\/status\.json)'/g
+const TOOL_RE = /['"`]((?:mcp__[a-z0-9-]+__)?[a-z][a-z0-9]*_[a-z0-9_-]*[a-z0-9])['"`]/g
+
+const readJson = (file) => {
+ try {
+ return JSON.parse(readFileSync(file, 'utf8'))
+ } catch {
+ return undefined
+ }
+}
+
+/** Every non-test .ts file under `dir`, recursively, as repo-relative-to-dir paths. */
+export function sourceFiles(dir) {
+ const out = []
+ const walk = (d) => {
+ for (const name of readdirSync(d).sort()) {
+ if (name === 'node_modules' || name === 'tests') continue
+ const p = join(d, name)
+ if (statSync(p).isDirectory()) walk(p)
+ else if (name.endsWith('.ts') && !name.endsWith('.d.ts') && !name.endsWith('.test.ts')) out.push(p)
+ }
+ }
+ if (existsSync(dir)) walk(dir)
+ return out
+}
+
+const all = (re, text) => [...text.matchAll(re)].map((m) => m[1] ?? m[2])
+const uniq = (xs) => [...new Set(xs)].sort()
+const sha = (text) => createHash('sha256').update(text).digest('hex').slice(0, 12)
+
+/** Test files of a plugin: the mod tests under tests/ plus any hooks/**\/*.test.ts. */
+export function testFiles(dir) {
+ const out = []
+ const walk = (d) => {
+ for (const name of readdirSync(d).sort()) {
+ if (name === 'node_modules') continue
+ const p = join(d, name)
+ if (statSync(p).isDirectory()) walk(p)
+ else if (/\.test\.(ts|mjs|js)$/.test(name)) out.push(relative(dir, p))
+ }
+ }
+ if (existsSync(join(dir, 'tests'))) walk(join(dir, 'tests'))
+ return out
+}
+
+/** `test('name'` and `it('name'` titles in a test file: what the matrix cites as proof. */
+export function testTitles(file) {
+ const text = readFileSync(file, 'utf8')
+ return [...text.matchAll(/\b(?:test|it)\(\s*(['"`])((?:\\.|(?!\1).)*)\1/g)].map((m) => m[2])
+}
+
+/** Everything the matrix records about one plugin directory. */
+export function scanPlugin(dir) {
+ const manifest = readJson(join(dir, '.claude-plugin', 'plugin.json')) ?? {}
+ const hooksJson = readJson(join(dir, 'hooks', 'hooks.json'))
+ const modules = Array.isArray(hooksJson?.modules) ? hooksJson.modules : []
+ const sources = sourceFiles(join(dir, 'hooks'))
+ const events = {}
+ const commands = { run: [], registered: [] }
+ const statusPaths = []
+ const statusRefs = []
+ const guardTools = []
+ let loc = 0
+ for (const file of sources) {
+ const text = readFileSync(file, 'utf8')
+ const rel = relative(join(dir, 'hooks'), file)
+ loc += text.split('\n').length
+ for (const e of all(EVENT_RE, text)) (events[e] ??= []).push(rel)
+ commands.run.push(...all(COMMAND_RUN_RE, text))
+ commands.registered.push(...all(COMMAND_REG_RE, text))
+ statusPaths.push(...all(STATUS_WRITE_RE, text))
+ statusRefs.push(...all(STATUS_ANY_RE, text))
+ if (/(^|\/)guard\//.test(rel) || /(^|\/)guard\.ts$/.test(rel)) guardTools.push(...all(TOOL_RE, text).filter((t) => /^(mcp__|[a-z]+_[a-z])/.test(t) && !t.startsWith('claude_')))
+ }
+ for (const k of Object.keys(events)) events[k] = uniq(events[k])
+ const userConfig = {}
+ for (const [key, spec] of Object.entries(manifest.userConfig ?? {})) userConfig[key] = { type: spec.type ?? null, default: spec.default ?? null }
+ return {
+ name: manifest.name ?? null,
+ version: manifest.version ?? null,
+ isMod: modules.length > 0,
+ modules,
+ classicFallback: Boolean(hooksJson?.hooks),
+ events,
+ commands: { run: uniq(commands.run), registered: uniq(commands.registered) },
+ statusPaths: uniq(statusPaths),
+ statusReads: uniq(statusRefs.filter((p) => !statusPaths.includes(p))),
+ guardTools: uniq(guardTools),
+ userConfig,
+ sourceFiles: sources.map((f) => relative(join(dir, 'hooks'), f)).sort(),
+ hookLoc: loc,
+ testFiles: testFiles(dir),
+ }
+}
+
+/** Groups plugin names by identical content of `file`; the biggest group is the generator's output, the rest drifted. */
+export function duplicateGroups(pluginsDir, plugins, file) {
+ const groups = new Map()
+ for (const p of plugins) {
+ const path = join(pluginsDir, p, 'hooks', file)
+ if (!existsSync(path)) continue
+ const h = sha(readFileSync(path, 'utf8'))
+ groups.set(h, [...(groups.get(h) ?? []), p])
+ }
+ return [...groups.entries()].map(([hash, names]) => ({ hash, plugins: names.sort() })).sort((a, b) => b.plugins.length - a.plugins.length)
+}
+
+/** Names claimed by more than one plugin, for a map of `plugin -> names[]`. */
+export function collisions(byPlugin) {
+ const seen = new Map()
+ for (const [plugin, names] of Object.entries(byPlugin)) for (const n of new Set(names)) seen.set(n, [...(seen.get(n) ?? []), plugin])
+ return Object.fromEntries([...seen.entries()].filter(([, ps]) => ps.length > 1).sort(([a], [b]) => a.localeCompare(b)))
+}
+
+/** Builds the whole matrix for a plugins directory; `counts` maps plugin name to a measured test count. */
+export function buildMatrix(pluginsDir, counts = {}) {
+ const names = readdirSync(pluginsDir).filter((n) => !n.startsWith('.') && statSync(join(pluginsDir, n)).isDirectory()).sort()
+ const rows = {}
+ for (const n of names) {
+ const row = scanPlugin(join(pluginsDir, n))
+ row.testCount = Object.hasOwn(counts, n) ? counts[n] : null
+ rows[n] = row
+ }
+ const mods = names.filter((n) => rows[n].isMod)
+ const by = (pick) => Object.fromEntries(mods.map((n) => [n, pick(rows[n])]))
+ const eventTotals = {}
+ for (const n of mods) for (const e of Object.keys(rows[n].events)) eventTotals[e] = (eventTotals[e] ?? 0) + 1
+ return {
+ schema: 1,
+ summary: {
+ plugins: names.length,
+ mods: mods.length,
+ withoutMod: names.filter((n) => !rows[n].isMod),
+ pluginsWithToolCallHook: mods.filter((n) => rows[n].events['tool.call']).length,
+ eventTotals,
+ testCountsSupplied: Object.keys(counts).length,
+ },
+ collisions: {
+ commandNames: collisions(by((r) => [...r.commands.run, ...r.commands.registered])),
+ statusPaths: collisions(by((r) => r.statusPaths)),
+ userConfigKeys: collisions(by((r) => Object.keys(r.userConfig))),
+ guardedTools: collisions(by((r) => r.guardTools)),
+ },
+ duplicates: Object.fromEntries(SHARED_FILES.map((f) => [f, duplicateGroups(pluginsDir, mods, f)])),
+ plugins: rows,
+ }
+}
+
+function parseArgs(argv) {
+ const args = { pluginsDir: 'plugins', counts: undefined }
+ for (let i = 0; i < argv.length; i++) {
+ if (argv[i] === '--plugins-dir') args.pluginsDir = argv[++i]
+ else if (argv[i] === '--counts') args.counts = argv[++i]
+ else throw new Error(`unknown argument: ${argv[i]}`)
+ }
+ return args
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+ const args = parseArgs(process.argv.slice(2))
+ const counts = args.counts ? readJson(args.counts) : {}
+ if (counts === undefined) throw new Error(`cannot read counts file: ${args.counts}`)
+ process.stdout.write(`${JSON.stringify(buildMatrix(resolve(args.pluginsDir), counts), null, 2)}\n`)
+}
diff --git a/v3/docs/validation/mod-capability-review-2026-10.md b/v3/docs/validation/mod-capability-review-2026-10.md
new file mode 100644
index 0000000000..16b67f1669
--- /dev/null
+++ b/v3/docs/validation/mod-capability-review-2026-10.md
@@ -0,0 +1,135 @@
+# Mod system capability review, 2026-10-04
+
+Scope: `plugins/ruflo-{mods,console,swarm,ruos,agentdb}`, the 39 ADR-446 per-plugin mods, ADRs 404, 444 to 448, and the CLI and guidance code they connect to. Base: `origin/main` a962c403e.
+
+Method and limits, stated up front:
+
+- The machine-checkable columns come from `node scripts/mod-capability-matrix.mjs` (reads files only; 8 node:test tests in `scripts/__tests__/mod-capability-matrix.test.mjs`).
+- Four read-only review agents read ADRs and code: ruflo-mods (ADR-404), agentdb/swarm/ruos (ADR-445, 405), guidance and cross-mod (ADR-447), console (ADR-444/448). The console agent was told to stop early on budget, so ADR-443 and the console's `/ruflo` command tests are "not checked".
+- **Nothing here was live-verified in a `claude -p` session.** The session budget ran out on the review agents before any live run. "Live-verified" is "no" in every row. What was run: `claude plugin validate` and `claude plugin test` (the engine kit, not a model session) on all 44 mods.
+- ADR-449 does not exist (`v3/docs/adr` stops at 448). The brief's reference to it is a mistake.
+
+## 0. Measured baseline
+
+| Check | Result |
+|---|---|
+| Plugin directories with `hooks/register.ts` | 44 (5 core mods + 39 per-plugin); `ruflo-core` and `ruflo-cost-tracker` have no mod, by ADR-446 design |
+| Mods registering `tool.call` | 40 of 44 (not `agntcy`, `arena`, `plugin-creator`, `ruos`) |
+| `claude plugin test`, all 44 | **647 pass, 20 fail** |
+| Failing plugins | agntcy 3, arena 4, graph-intelligence 11, plugin-creator 1, **console 1** |
+| `claude plugin validate` | passes for all 44; warnings for arena, graph-intelligence, workflows |
+| Static test titles (`test(`/`it(` grep) | 751; the run count differs (console static 138 vs 210 run, parametrised tests), so static counts are not a substitute |
+
+ADR-446 explained the agntcy/arena/graph-intelligence/plugin-creator failures as the harness loading non-mod vitest files. **The console failure is not explained there and was not investigated here.** First thing to look at: `cd plugins/ruflo-console && claude plugin test`.
+
+## 1. Capability matrix
+
+Columns: where, events, default, proof (test file::title), live-verified (all "no"), known gaps. `P:` = `plugins/<name>/tests/`; `C:` = `v3/@claude-flow/cli/__tests__/mods/` (the only one CI runs; the `P:` kit tests are not in CI).
+
+| Capability | Where | Events | Default | Proof | Gaps |
+|---|---|---|---|---|---|
+| In-process routing | ruflo-mods `route/*` | prompt.submit | on if mod owns `route` | P:register "routes a prompt in-process: the route rides as context, #3567 no-match included"; C:mods-route "carries router.cjs TASK_PATTERNS exactly" | none found |
+| Tighten-only tool.check | ruflo-mods `guard/*` | tool.check | on | P:register "tool.check: the dangerous-command list tightens an allow; a deny is never loosened"; C:mods-guard (3x3 verdict loop) | research guard (ADR-440) missing from ADR-404 and README |
+| Edit learning | ruflo-mods `learn/*` | tool.call, turn.complete, session.end | on if mod owns `post-edit` | P:register "records a finished edit once per turn, in the classic pending-insights format" | session.end flush untested; `FLUSH_AT=50` flushes early |
+| Cost ladder | ruflo-mods `cost/*` | session.measure, agent.spawn | **off** (`costBudgetUsd` 0) | P:cost "the budget ladder says each rung once on the way up; HARD_STOP halts new agents" | rung re-announced if cost falls and rises (`cost/index.ts:166`) |
+| Secret guard (ruflo-mods) | none | none | n/a | none | **claimed, no code**: `guard/` has no secret logic (see 2) |
+| Recall into prompt | ruflo-agentdb `recall.ts` | prompt.submit | **off** | P:register "on: attaches screened memory as framed per-prompt context, once per prompt (cached after)" | deadline bounds `read` only |
+| Memory write guard | ruflo-agentdb + 38 per-plugin `guard.ts` | tool.call | on | P:register "refuses a secret in a memory write, passes a clean one, ignores other tools" | **fails open**, see 4 |
+| Console control by Claude | ruflo-console `model-tools.ts`, `register.ts:215` | tool.call (own `mcp__ruflo-console__*` names) | **off** setting `modelControl`; confirm `auto` | model-tools.spec "refuses and cancels an action above the level, even in auto mode: nothing runs"; "are four, each with an object schema…" | level gate bypassed by remembered "always" actions (4, item 7) |
+| Room feed (ADR-448) | ruflo-console `hooks/{room,data/room,views/room}.ts` | in-memory events, control log | named-only page | room.spec "interleaves events, Claude's console actions and what was said, newest first" | memory only (WeakMap, cap 50): not "shared" across sessions; no ✦ ask buttons in "Who's here" |
+| Mods section | ruflo-console `data/mods.ts`, `views/mods.ts` (rendered on the Room page, counted on Overview) | reads `.claude-flow/<x>-mod/status.json`, 60 folders, 8 KB, version 1 | on | mods-section.spec "reads only *-mod folders and skips a folder with no status file"; "caps the folders read at 60 and says so" | ADR-446 "console does not list them yet" is stale: it does |
+| Status files | 38 per-plugin `status.ts` + agentdb | session.start, tool.call | on | per plugin `mod.test.ts` | one reader (console, agentdb only); 38 writers with no reader |
+| `/<x>-mod` commands | per-plugin `command.ts` | command.run | on | e.g. ruflo-adr P:mod "status and scan answer locally" | `/agentdb-mod` README text describes the wrong command (2) |
+| Trust gate | ruflo-mods `trust.ts` | plugin.register | `modTrust` observe | P:trust "observe (default): names what a later mod can do, and loads it" | none found |
+| Handshake ownership | ruflo-mods `session.ts`, `ownership.ts`; CLI `hook-handler.cjs` | session.start | on | C:mods-ownership "exactly one routing block per prompt with a handshake-aware helper (the mod)" | none found |
+| Guidance observation | ruflo-mods `guidance/*` | inside existing handlers | **off** (both options) | P:guidance "default settings add no guidance or candidate observations"; "native lifecycle stores only unverified metadata once, with failures and final denies" | one manual reader (`ruflo guidance mod-candidates`); learning-only mode records no rule ids |
+| Swarm pane | ruflo-swarm | ui.render, ui.close, command.run, turn.*, agent.spawn, tool.call | `panel` command | P:register "by default (panel command) nothing opens unasked…" | `panel: off` does not stop `/ruflo swarm pane` |
+| Swarm CLI buttons | ruflo-swarm `actions/` | pane actions | npx-offline | controller.test "stealing a task asks first, then runs one fixed argv and checks the claim moved on disk" | none found |
+| ruos segment | ruflo-ruos | session.start, prompt.submit, 15 s clock | on | mod.test "sets the ruos segment from hosts.json and clears it when agents finish" | none found |
+
+The generated half (per-plugin events, userConfig, status paths, guarded tools) is the JSON from the script; regenerate rather than copying numbers from this file.
+
+## 2. Claims versus reality
+
+Not substantiated, stale or wrong:
+
+1. **ruflo-mods README:20** says ruflo-console is "pending until released". It is released and `required: true` in `install.ts`.
+2. **ADR-404 testing table** quotes "engine kit 15/15", "harness 99/99", "smoke ruflo-mods 10/10", "plugin-creator 11/11". Actual: 28 kit tests; about 147 `it(` calls in `__tests__/mods`; smoke has 11 steps; plugin-creator smoke has 15.
+3. **ADR-404** says plugin-creator 0.3.0 adds `create-mod`; it is 0.4.0.
+4. **ADR-404 and README** omit the research guard (`guard/research.ts`), the `command.run` events and the guidance loop in the behaviour tables.
+5. **ruflo-mods `plugin.json` / `marketplace.json`** still say "opt-in"; Amendment 1 made it the `ruflo init` default.
+6. **ADR-404 security model** says "no secrets"; enforced only by smoke step 8 (a regex for `key = "literal"`). The brief's "secret guard" for ruflo-mods does not exist.
+7. **ruflo-swarm `plugin.json`**: `panel: off` "never opens it" is wrong. The `pane` subcommand calls `openPane()` with no option check (`register.ts:313-325`); only auto-open and `:watch` are gated. No test sets `panel: 'off'`.
+8. **ruflo-agentdb**: README:63 describes `/agentdb-mod` as health and session management (that is the markdown `/agentdb`); README:5 says v0.3.0 (plugin is 0.4.0); the `plugin.json` description and `register.ts:123` docstring say `/agentdb`, the real mod command is `/agentdb-mod`.
+9. **ADR-445 §6** says all hook files are "under 120 lines"; `register.ts` is 171.
+10. **ADR-445 and README** list six guarded writers; `WRITERS` has seven (`hooks_intelligence_pattern-store`). Judged from names only, these write tools are unguarded: `agentdb_feedback`, `agentdb_session-end`, `hive-mind_memory`, `memory_import`, `session_save`, `rvf_ingest`, `hooks_compress_store`.
+11. **Swarm activity file** `.claude-flow/metrics/swarm-activity.json`: nothing in the swarm plugin writes or reads it; the CLI and hooks code reference it. Writer not traced.
+12. **ADR-447 numbers** "47 contract cases" and "189 tests across 10 files" could not be reconciled by static count (about 45 and about 150). Not run, so unverified rather than wrong.
+13. **ADR-446** is dated 2026 10 05; today is 2026-10-04.
+14. **ADR-446** says the plugins are "unchanged" for the five existing mods and "46 of 46" smoke; this review found 46 plugin directories with a manifest, 44 with mods. Not re-run.
+15. **The brief's** "ADR-449" does not exist.
+16. **ADR-444** status is "Proposed" but it ships (Settings rows `model-control`, `model-confirm`). "Anything unclear counts as the most dangerous class" is wrong: `classOf` falls through to `write` (`model-tools.ts:60`). "270 palette entries; 105/101/27/2/4+" is pinned by no test and the parts sum to 239.
+17. **ADR-448** scope says `palette.ts` and `runner.ts(ask)` changed and `console_state` reads the feed; no room code is in `palette.ts` or `model-tools.ts`. "Shared" feed is in-memory per session. "vitest 871" is stale (about 961 test lines in 101 files). Line references are off by 1 to 3.
+18. **ruflo-console `plugin.json`** description omits Missions, Room, Mods, Sandbox, Secure, Perf, Automate, Neural, Vector, Evolve, Dev Tools, Market, Settings and the plugin catalog.
+19. **ADR-446 "39 mods"** versus 34 `-mod` commands and 35 `status.ts` files found by the console agent; the generator counts 44 mods in all. Reconcile with the matrix JSON.
+20. `/ruflo` and `/ruflo-console` are hooked by three plugins (console, ruflo-mods `session.ts:89`, ruflo-swarm `register.ts:353`); delegation relies on each calling `next`.
+
+Verified and matching: ruflo-mods userConfig defaults (8 keys, `plugin.json` = `options.ts` = README); agentdb "26 tests" (12 + 14); registration order matches its comment (trust outermost); guidance defaults both off; guidance tighten-only (`stricter()` returns ours only when strictly higher; the research guard was not read); CLI `mods` subcommands exist.
+
+## 3. Cross-mod interactions
+
+- **Stacking.** A denying guard returns `{ deny }` without calling `next`, a passing one returns `next(e)`; by ADR-404 "first registered wraps the rest", the outer denier short-circuits, so two mods cannot both emit a reason for one call. Which plugin is outer across plugins is engine-defined and **not verified**.
+- **Overlapping watchers.** `memory_store` is named in 15 guard files, `agentdb_hierarchical-store` in 12, `agentdb_pattern-store` in 10 (generator, guard files only). Several guards (music, agentdb, rag-memory) screen every write with no namespace check, others are namespace-gated (security-audit, goals, intelligence).
+- **False refusal across plugins (from reading, not executed).** With ruflo-music or ruflo-agentdb installed, a `memory_store` of a fixture holding a fake `AKIA…` key into any namespace is refused, and the reason names that plugin even if the user's task is the security-audit plugin's.
+- **No command-name collisions.** Zero shared registered names across 44 mods; none equal a markdown command name. `ruflo-swarm:watch` wraps the markdown command and calls `next`, deliberately.
+- **Status paths.** No two mods write the same path; the generator's only repeated path is console reading `agentdb-mod/status.json`.
+- **userConfig keys.** `guard` is declared by 36 plugins, `cli` and `panel` by console and swarm. Whether Claude Code namespaces them per plugin was not verified here; if it does not, they collide.
+- **Reads of other mods' files.** Only console reads one mod file (agentdb status). Console and swarm also read CLI-written stores under `.claude-flow/`.
+
+## 4. Real defects found
+
+1. **The memory write guard fails open.** Reproduced by an agent against a copy of `screen.ts`, `guard.ts` and `tools.ts`. A `ghp_` token passes when it is: after char 20,000 of one string (`bare()` slices before the regex); after about 20k characters of earlier fields (the `textsOf` budget returns `[]`); an object key (`Object.values` skips keys); item or field 201; depth 7 (depth 6 is blocked); split across two fields; base64. **`{password: "<20 chars>"}` and `{key: "api_key", value: "..."}` also pass**, because the key-assignment regex needs name and value in one string and structured input splits them. This affects JSON-shaped writes such as `agentdb_hierarchical-store` and `agentdb_batch`. No test covers truncation, budget, keys or structured credentials. The same `textsOf`/`bare` pair is copied into the other mods (ADR-446 §3), so the other 38 guards very likely share it; only agentdb's was reproduced.
+2. **`panel: off` is not honoured** by the pane subcommand (claim 7).
+3. **Cost rung re-announced** after cost falls then rises (`cost/index.ts:166-169`); contradicts "once per rung".
+4. **`guidance.prompt` runs before the `owned.has('route')` check** (`route/index.ts:236`), so with `guidanceLearning` on, a project that does not own routing still records guidance observations. README:72 promises no writes there.
+5. **Observation loss past 256 tool ids per task** is silent beyond the status line.
+6. **Console `claude plugin test` has 1 failure** (cause not investigated).
+7. **Console level gate bypass.** `runner.ask` runs an action whose kind is in `state.allowed` at once, with no pending action; `console_run` classifies only pending actions (`runner.ts:135-141`, `model-tools.ts:285-291`). After a person picks "always" on a write, network or delete action, Claude at level `read` can run it by id and get "Done" without reaching `allows()`. Not reproduced live.
+8. `runById` runs `filterPalette(text)[0]` when the id is missing and `text` is set (`runner.ts:204`), so a typo'd id can run a different entry (class gate still applies).
+
+## 5. Dead and duplicate code
+
+- **Screen:** `screen.ts` exists in 38 mods in 18 distinct byte-variants (group sizes 17, 5, then 16 singletons). `status.ts`, `command.ts` and `guard.ts` are not byte-identical in any two plugins (they carry per-plugin names and rules); `options.ts` has 21 variants (largest group 9). The shared logic (secret regex set, `textsOf`, `splitName`, flag parsing, `statusText`) has no owner. Drift is already real: the browser copy adds `nsec1`, the injection set is absent in some.
+- A fourth secret-regex implementation lives in `ruflo-mods/hooks/guidance/screen.ts`, whose header still says "for the AgentDB mod"; its `hasSecret` and `tidy` have no callers.
+- `PLUGIN_NAME` (`ruflo-swarm/hooks/state.ts:8`), `parseProbe` (`ruflo-ruos/scripts/lib/command-builder.mjs:235`): exported, never used.
+- `isStrings` duplicated (`trust.ts`, `policy.ts`); the control-character stripper is written three times with different ranges (agentdb, ruos, swarm).
+- No hook file is over 500 lines individually (largest `ruflo-swarm/hooks/register.ts`, 466). A `wc` total over the console `hooks/` tree is large (28k lines including catalog data); the per-file claim was checked only for agentdb, swarm and ruos by agents.
+- `scripts/native-guidance-smoke.sh` embeds inline `python3`, against the user-level "Rust only, never Python" rule (the project CLAUDE.md in this worktree has no such rule).
+
+## 6. Fifteen highest-value improvements
+
+| # | Change | Impact | Effort | Targets |
+|---|---|---|---|---|
+| 1 | Make the guard scan complete: keys with values, `key=value` pairs, overlapping windows, fail closed above caps, raise the item and depth limits | high (a real secret leak path) | S | `plugins/ruflo-agentdb/hooks/{guard,screen}.ts` first |
+| 2 | One generated shared module (`screen`, `textsOf`, `splitName`, `readOptions` flag, `statusText`) vendored at release with a drift check that fails CI on any hash outside the generator output | high | M | `plugins/ruflo-plugin-creator/templates/mod/hooks/`, new `scripts/vendor-mod-kit.mjs`; use `duplicates` from the matrix script |
+| 3 | Regression tests for truncation, budget, key, structured credential in every guard | high | S | `plugins/*/tests/mod.test.ts` (generate) |
+| 4 | Investigate and fix the console `claude plugin test` failure; make the 4 non-mod vitest files invisible to the kit | high | S | `plugins/ruflo-console/tests/`, `ruflo-{agntcy,arena,graph-intelligence,plugin-creator}` |
+| 5 | Run the 44 kit suites in CI (today only `C:` tests are in CI) | high | M | `.github/workflows/` (new job using `claude plugin test` per plugin) |
+| 5b | Classify remembered actions in `console_run` (run `allows()` before `ask`), and fix the `classOf` comment or fall-through | high | S | `plugins/ruflo-console/hooks/{model-tools,runner}.ts`, `tests/model-tools.spec.ts` |
+| 6 | Honour `panel: off` for the `pane` subcommand and add the test | med | S | `plugins/ruflo-swarm/hooks/register.ts:313`, `tests/register.test.ts` |
+| 7 | Fleet check that each guarded tool name exists in the tool registry (ADR-446 follow-up) | med | S | generator `guardTools` + CLI tool list, new test in `scripts/__tests__/` |
+| 8 | Narrow overlapping `memory_store` guards: namespace gate or one owner, so an unrelated plugin cannot refuse a write | med | M | `ruflo-{music,agentdb,rag-memory}/hooks/guard.ts` |
+| 9 | Console Mods section that lists all 39 `<x>-mod/status.json` (version-checked, like agentdb's) | med | M | `plugins/ruflo-console/hooks/data/files.ts` and the settings page |
+| 10 | Correct stale docs: claims 1 to 5, 8, 9, 13 above; replace the ADR-404 test table with generated counts | med | S | `plugins/ruflo-mods/README.md`, ADR-404, ADR-445, ADR-446, `ruflo-agentdb/{README.md,.claude-plugin/plugin.json}` |
+| 11 | Gate `guidance.prompt` on ownership; give learning-only mode rule ids or document it | low-med | S | `plugins/ruflo-mods/hooks/route/index.ts:236`, `guidance/index.ts:46` |
+| 12 | Track highest rung, not last, in the cost ladder | low | S | `plugins/ruflo-mods/hooks/cost/index.ts:166` |
+| 13 | Drop dead exports and the copied header | low | S | `guidance/screen.ts`, `swarm/hooks/state.ts`, `ruos/scripts/lib/command-builder.mjs` |
+| 14 | Prove the live paths the table marks "no": routing, deny, status file, `/x-mod` via `claude -p` haiku, in a private scratch dir, and record the evidence | med | M | `plugins/ruflo-mods/scripts/smoke.sh` pattern |
+| 15 | Resolve who writes and reads `swarm-activity.json` and the 38 unread status files, or remove the writers | low-med | M | `v3/@claude-flow/hooks/src/statusline`, per-plugin `status.ts` |
+
+## 7. Not done
+
+- No live model sessions (budget), so nothing is marked live-verified.
+- ADR-443, the console `/ruflo` command tests and the writers of the console's `.claude-flow` input files were not checked.
+- Latency and bench figures, "10,000 comparisons" parity and git-hardening claims in `mod-sources.ts` were not re-run.
+- No in-repo doc fixes applied; claims 1 to 9 are listed for the owners.