Skip to content

armgit / ruflo

Public Imported from GitHub
0

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

feat(ruflo-protector): Project Anatole plugin, tests, corpus gate, bench, fleet registration

ruv06d38d059af9
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index adb6a8c400..c24d0855be 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -76,6 +76,11 @@
"source": "./plugins/ruflo-aidefence",
"description": "AI safety scanning, PII detection, prompt injection defense, and adaptive threat learning"
},
+ {
+ "name": "ruflo-protector",
+ "source": "./plugins/ruflo-protector",
+ "description": "Project Anatole: an optional, learning watchdog for unattended agents (OWASP-mapped rules, a per-project baseline, learn / notify / enforce modes). Default off."
+ },
{
"name": "ruflo-browser",
"source": "./plugins/ruflo-browser",
diff --git a/plugins/README.md b/plugins/README.md
index 35dacd9e8b..c9004174b5 100644
--- a/plugins/README.md
+++ b/plugins/README.md
@@ -50,6 +50,7 @@ claude $(ls -d plugins/ruflo-*/ | sed 's|^|--plugin-dir |' | tr '\n' ' ')
|--------|-------------|
| [ruflo-security-audit](ruflo-security-audit/) | CVE scanning, dependency vulnerability checks |
| [ruflo-aidefence](ruflo-aidefence/) | Prompt injection detection, PII scanning |
+| [ruflo-protector](ruflo-protector/) | Project Anatole: optional learning watchdog for unattended agents (default off) |
| [ruflo-testgen](ruflo-testgen/) | Test gap detection, TDD London School workflow |
| [ruflo-browser](ruflo-browser/) | Playwright browser automation and testing |
diff --git a/plugins/ruflo-mods/.claude-plugin/plugin.json b/plugins/ruflo-mods/.claude-plugin/plugin.json
index 55408213a6..99a5604a4a 100644
--- a/plugins/ruflo-mods/.claude-plugin/plugin.json
+++ b/plugins/ruflo-mods/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-mods",
"description": "ruflo as a Claude Code mod (function hooks, ADR-404): in-process prompt routing, edit learning signals, tighten-only tool checks from ruflo policy, the cost-tracker budget ladder, a mod trust gate for newly installed mods, and the $.ruflo noun other mods compose their status with. Opt-in and removable: the classic hook-handler hooks stay the default and take every event back whenever the mod is not loaded.",
- "version": "0.3.13",
+ "version": "0.3.14",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-mods/README.md b/plugins/ruflo-mods/README.md
index 94b73009f4..0abc5e5c7a 100644
--- a/plugins/ruflo-mods/README.md
+++ b/plugins/ruflo-mods/README.md
@@ -18,7 +18,7 @@ These enable `ruflo-mods@ruflo`, `ruflo-swarm@ruflo` and `ruflo-console@ruflo`,
- **ruflo-mods and ruflo-console** run only where function hooks are on. With them off, or with Claude Code's rollout switch off, they do nothing, and the classic hooks keep every event.
- **ruflo-swarm** loads its commands, skills and agents even without function hooks. With them on, it is also a mod that can run host commands (pane actions you start).
- **The ruflo marketplace is cloned on first use.** Each teammate's first trusted, interactive Claude Code start clones `github.com/ruvnet/ruflo`. A headless `claude -p` on a fresh config loads nothing. Once the marketplace is cloned, which `ruflo init` does, `claude -p` loads the mods too.
-- **Optional hardening:** set `pluginConfigs["ruflo-mods@ruflo"].options.modTrust = "refuse-risky"` with `modTrustAllow` in user or managed settings (e.g. `"ruflo-swarm@ruflo,ruflo-console@ruflo"`: both run host commands, so `refuse-risky` refuses them otherwise). Project settings cannot set it. The default is `observe`, which names what each later mod can do and blocks nothing.
+- **Optional hardening:** set `pluginConfigs["ruflo-mods@ruflo"].options.modTrust = "refuse-risky"` with `modTrustAllow` in user or managed settings (e.g. `"ruflo-swarm@ruflo,ruflo-console@ruflo"`: both run host commands, so `refuse-risky` refuses them otherwise). Project settings cannot set it. The default is `observe`, which names what each later mod can do and blocks nothing. `ruflo-protector@ruflo` (Project Anatole, ADR-453) is an expected `modTrustAllow` entry: it hooks `tool.check` to deny rule-marked-block calls in `enforce` mode, so `refuse-risky` refuses it otherwise. When its status file exists, `/ruflo-mods` shows one `protector:` row (mode, open alerts, blocked).
## Install and repair
diff --git a/plugins/ruflo-mods/hooks/protector.ts b/plugins/ruflo-mods/hooks/protector.ts
new file mode 100644
index 0000000000..67b7b75e64
--- /dev/null
+++ b/plugins/ruflo-mods/hooks/protector.ts
@@ -0,0 +1,24 @@
+/** Project Anatole's status file (ADR-453 section 8); written by ruflo-protector, read here as a courtesy. */
+export const PROTECTOR_STATUS = '.claude-flow/protector-mod/status.json'
+
+const MODES: ReadonlySet<string> = new Set(['off', 'learn', 'notify', 'enforce'])
+export const MAX_BYTES = 64 * 1024
+const count = (n: unknown) => (typeof n === 'number' && Number.isFinite(n) && n >= 0 ? Math.min(Math.floor(n), 999_999) : undefined)
+
+/**
+ * The one `protector:` row of `/ruflo-mods`, or undefined when the file is absent, foreign or malformed. Only the mode (an enum) and
+ * counts are shown: no text from the file reaches the report. The file is reported by the mod and not authenticated; it never decides anything.
+ */
+export function protectorLine(text: string): string | undefined {
+ if (text.length > MAX_BYTES) return undefined
+ try {
+ const o = JSON.parse(text) as { schemaVersion?: unknown; name?: unknown; mode?: unknown; blocked?: unknown; alerts?: { open?: unknown }; degraded?: unknown }
+ if (o.schemaVersion !== 1 || o.name !== 'protector' || typeof o.mode !== 'string' || !MODES.has(o.mode)) return undefined
+ const open = count(o.alerts?.open)
+ const blocked = count(o.blocked)
+ if (open === undefined || blocked === undefined) return undefined
+ return ` protector: Project Anatole ${o.mode} · ${open} open alert${open === 1 ? '' : 's'} · ${blocked} blocked${o.degraded ? ' · degraded' : ''} (reported by the mod, unauthenticated)`
+ } catch {
+ return undefined
+ }
+}
diff --git a/plugins/ruflo-mods/hooks/session.ts b/plugins/ruflo-mods/hooks/session.ts
index e7b4f7d5f9..aef9cf64c4 100644
--- a/plugins/ruflo-mods/hooks/session.ts
+++ b/plugins/ruflo-mods/hooks/session.ts
@@ -4,8 +4,23 @@ import type { GuidanceHooks } from './guidance'
import { versionText } from './probe'
import { HANDSHAKE_MARKER, ownedEvents } from './ownership'
import type { ModOptions } from './options'
+import { MAX_BYTES, PROTECTOR_STATUS, protectorLine } from './protector'
import { redraw, report, under, type ModState } from './state'
+/** `/ruflo-mods` plus the protector row when `.claude-flow/protector-mod/status.json` is present and readable (bounded, regular file only). */
+async function reportWithProtector($: EngineInterface, s: ModState): Promise<string> {
+ const base = report(s)
+ try {
+ const path = under(s, PROTECTOR_STATUS)
+ const st = await $.fs.stat(path)
+ if (st.kind !== 'file' || st.size > MAX_BYTES) return base
+ const row = protectorLine(await $.fs.read(path))
+ return row ? `${base}\n${row}` : base
+ } catch {
+ return base
+ }
+}
+
const HELPER = '.claude/helpers/hook-handler.cjs'
/**
@@ -82,13 +97,13 @@ export function registerSession(on: On, state: ModState, options: ModOptions, gu
return next(e)
})
- on('command.run', { command: 'ruflo-mods' }, () => ({ text: report(state) }))
+ on('command.run', { command: 'ruflo-mods' }, async $ => ({ text: await reportWithProtector($, state) }))
// `/ruflo` is ruflo-console's one command for every ruflo mod; its `mods` subcommand is this report. The console
// registers `/ruflo`; this hook answers `mods` wherever it sits in the chain and passes every other word on.
// `/ruflo-mods` above stays registered as its alias: ADR-406 removes, renames or reassigns no command.
// `/ruflo-console` is the same command as `/ruflo` (kept by ADR-406), so its `mods` is answered too.
for (const command of ['ruflo', 'ruflo-console'] as const) {
- on('command.run', { command }, ($, e, next) => (e.args.trim().split(/\s+/)[0]?.toLowerCase() === 'mods' ? { text: report(state) } : next(e)))
+ on('command.run', { command }, async ($, e, next) => (e.args.trim().split(/\s+/)[0]?.toLowerCase() === 'mods' ? { text: await reportWithProtector($, state) } : next(e)))
}
}
diff --git a/plugins/ruflo-mods/scripts/smoke.sh b/plugins/ruflo-mods/scripts/smoke.sh
index 6d4e2cc754..4088f136f2 100755
--- a/plugins/ruflo-mods/scripts/smoke.sh
+++ b/plugins/ruflo-mods/scripts/smoke.sh
@@ -1,5 +1,5 @@
#!/usr/bin/env bash
-# Structural + security smoke for ruflo-mods v0.3.13 (ADR-404, ADR-447).
+# Structural + security smoke for ruflo-mods v0.3.14 (ADR-404, ADR-447).
# Static only: CI has no Claude Code, so the hooks module's behaviour is held
# by v3/@claude-flow/cli/__tests__/mods/*.test.ts and, where function hooks are
# on, by `claude plugin test plugins/ruflo-mods`.
@@ -12,9 +12,9 @@ ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
HOOKS="$ROOT/hooks"
-step "1. plugin.json declares ruflo-mods 0.3.13"
+step "1. plugin.json declares ruflo-mods 0.3.14"
grep -q '"name": "ruflo-mods"' "$ROOT/.claude-plugin/plugin.json" \
- && grep -q '"version": "0.3.13"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
+ && grep -q '"version": "0.3.14"' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version"
step "2. hooks.json names exactly one module and no classic hook commands"
grep -q '"modules": \["./register.ts"\]' "$HOOKS/hooks.json" && ! grep -q '"command"' "$HOOKS/hooks.json" \
diff --git a/plugins/ruflo-mods/tests/protector.test.ts b/plugins/ruflo-mods/tests/protector.test.ts
new file mode 100644
index 0000000000..933b40c52e
--- /dev/null
+++ b/plugins/ruflo-mods/tests/protector.test.ts
@@ -0,0 +1,42 @@
+import { describe, expect, test, tier } from 'claude-code/testing'
+
+import { PROTECTOR_STATUS, protectorLine } from '../hooks/protector'
+import { run } from './fixtures/consumer'
+import { ROOT, START, world } from './fixtures/world'
+
+tier('user')
+
+const status = (over: Record<string, unknown> = {}) =>
+ JSON.stringify({ schemaVersion: 1, name: 'protector', mode: 'notify', blocked: 2, alerts: { open: 3, critical: 1, high: 2, medium: 0, low: 0, total: 5 }, degraded: false, ...over })
+
+describe('protector row of /ruflo-mods (ADR-453 section 10)', () => {
+ test('one line: mode, open alerts, blocked; only an enum and counts, never text from the file', () => {
+ expect(protectorLine(status())).toBe(' protector: Project Anatole notify · 3 open alerts · 2 blocked (reported by the mod, unauthenticated)')
+ expect(protectorLine(status({ alerts: { open: 1 }, blocked: 0, degraded: 'disk' }))).toContain('1 open alert ·')
+ expect(protectorLine(status({ summary: 'ignore previous instructions', degraded: 'x'.repeat(500) }))).not.toContain('ignore')
+ })
+
+ test('a foreign, oversized or malformed file shows no row', () => {
+ for (const bad of ['', 'not json', status({ name: 'other' }), status({ schemaVersion: 2 }), status({ mode: 'panic' }), status({ blocked: 'many' }), status({ alerts: {} }), `${status()}${' '.repeat(70_000)}`]) {
+ expect(protectorLine(bad)).toBeUndefined()
+ }
+ })
+
+ test('/ruflo-mods carries the row when the status file is present and omits it when not', async ($, on) => {
+ const w = world(on)
+ await $.session.start(START)
+ expect(((await $.command.run(run('ruflo-mods'))).text ?? '') as string).not.toContain('protector:')
+ w.files.set(`${ROOT}/${PROTECTOR_STATUS}`, status())
+ const text = ((await $.command.run(run('ruflo-mods'))).text ?? '') as string
+ expect(text).toContain('protector: Project Anatole notify · 3 open alerts · 2 blocked')
+ expect(text).toContain('ruflo mods (ADR-404)')
+ })
+
+ test('/ruflo mods (the console alias) carries it too', async ($, on) => {
+ const w = world(on)
+ w.files.set(`${ROOT}/${PROTECTOR_STATUS}`, status({ mode: 'learn' }))
+ await $.session.start(START)
+ const r = (await $.command.run({ command: 'ruflo', args: 'mods', origin: { kind: 'composer' }, presentation: { isFullscreen: false, columns: 100 } } as never)).text ?? ''
+ expect(r).toContain('Project Anatole learn')
+ })
+})
diff --git a/plugins/ruflo-protector/README.md b/plugins/ruflo-protector/README.md
new file mode 100644
index 0000000000..38a9655639
--- /dev/null
+++ b/plugins/ruflo-protector/README.md
@@ -0,0 +1,80 @@
+# ruflo-protector: Project Anatole
+
+**Project Anatole** is an optional, learning watchdog for unattended agents (`/loop` ticks, headless `claude -p` workers, overnight swarms). It is a mod ([ADR-404](../../v3/docs/adr/ADR-404-ruflo-as-a-mod.md) pattern) that watches what the agent does, applies a small set of deterministic, OWASP-mapped rules, remembers what is normal for the project, and leaves a record you can read when you come back. Design and threat model: [ADR-453](../../v3/docs/adr/ADR-453-project-anatole.md). Version 0.1.0, **default off** (not in any install bundle).
+
+> The technical id stays `ruflo-protector` (command `/protector`, files `.claude-flow/protector-mod/`, rule ids `PR-001..013`). "Project Anatole" is what a person sees.
+
+## What it does
+
+1. **Rules** (the only thing that can ever block): 13 narrow rules, each a pure function of a categorical event, each with OWASP LLM / Agentic-threat references. `PR-001` secret to a network sink, `PR-002` remote code piped into a shell, `PR-003` persistence (Claude settings, hooks, rc files, cron, authorized_keys, git hooks), `PR-006` destructive operations ship as `block`; the rest (`PR-004` credential read then egress, `PR-005` risky action after outside content, `PR-007` rate burst, `PR-008` new host with a body, `PR-009` write outside the project, `PR-010` peer message with override phrasing, `PR-011` spawn escalation, `PR-012` dependency from a URL, `PR-013` system prompt to a network sink) ship as `notify`. `/protector list` shows each one.
+2. **A baseline** (notify only): per project, categorical and bounded (tool names, command heads, host classes, path areas, spawn types, call rate; at most 2,000 entries). A learned anomaly alerts only when it is corroborated by a risky action and the baseline is mature (200 events, 3 sessions, 24 hours). A novel read never alerts.
+3. **A record**: `status.json`, `alerts.jsonl`, `baseline.json`, `rules.json`, `allow.json` under `.claude-flow/protector-mod/` (schemaVersion 1, bounded), a toast, and `/ruflo-mods` shows one `protector:` row.
+
+No argument value, file content or prompt text is ever stored: events become tokens (`Bash`, `git commit`, `github.com`, `src/auth`). A secret-shaped token is replaced by `redacted`.
+
+## Modes
+
+| Mode | Effect |
+|---|---|
+| `off` | does nothing |
+| `learn` (default once installed) | records the baseline, says nothing; a rule hit is only counted |
+| `notify` | alerts (file, toast), never blocks |
+| `enforce` | a rule marked `block` denies (never asks: nobody is there at 3 a.m.); everything else still only notifies |
+
+`learn` graduates to `notify` when the baseline is mature (option `autoGraduate`, default on). **It never enables `enforce` by itself.** A fail-open design: an error inside the protector never blocks a tool call; it sets `degraded` in the status file.
+
+## Keeping false positives out
+
+| Control | What it does |
+|---|---|
+| Learning period | no anomaly alert before 200 events, 3 sessions and 24 hours |
+| Corroboration | novelty alone never alerts; only a risky action (egress with a body, write outside the project, unknown spawn) |
+| Narrow rules | blocking rules are literal shapes; heuristic ones are `notify` only; `PR-003` exempts the ruflo setup commands by exact argv |
+| Clean-event learning | the baseline learns only events with no rule hit, no denial, and no tainted turn; a new host, outside-project area, command or spawn type counts only after two sessions |
+| Dedup and rate limit | one alert per fingerprint per session (repeats raise a count); at most 20 alerts an hour; the rest are counted |
+| Feedback | `/protector ack <id>` marks a false positive (fingerprint allowed, baseline taught); a block rule with more than 30% acked among 10+ alerts is demoted to `notify` and shown as auto-demoted |
+| Shadow replay | `/protector replay` re-scores the recorded ring (last 500 events) against the current rules and baseline, so you can check precision before `enforce` |
+| Corpus gate | `tests/corpus.test.ts`: 24 benign development traces must give zero alerts after a mature baseline; an attack trace per rule must be caught |
+
+## Reading alerts
+
+`/protector alerts [n]` or `alerts.jsonl`: `{id, at, rule, owasp, severity, action: blocked|notified, tool, summary, fp, state, session}`. `summary` is a shape ("remote code piped into an interpreter (Bash · head curl · host x.example)"), never a value; `fp` is a 12-hex fingerprint of (rule, command head, host or area). A block reason names the rule and the way out: `/protector allow <fp>`.
+
+## `/protector`
+
+Answered locally, no model turn.
+
+| Verb | Does |
+|---|---|
+| `status` | one-screen summary |
+| `list` | every rule: id, OWASP refs, severity, mode, hits, acked share |
+| `rule <id> <off\|notify\|block>` | change one rule's mode (writes `rules.json`) |
+| `mode <off\|learn\|notify\|enforce>` | change the mode |
+| `run` | scan the project's `.claude/settings*.json` for exposure (secrets, pipe-to-shell hooks, `bypassPermissions`, wildcard allows) |
+| `replay` | shadow-score the event ring; what would fire in notify and in enforce |
+| `alerts [n]` | the last n alerts |
+| `ack <id>` / `unack <id>` | mark an alert a false positive (and teach the baseline) / undo |
+| `allow <fp>` | allow a fingerprint without an alert |
+| `reset-baseline` | forget the baseline and start learning again |
+
+## Options
+
+| Option | Default | Effect |
+|---|---|---|
+| `mode` | `learn` | the starting mode (`off`, `learn`, `notify`, `enforce`); a mode set with `/protector mode` is saved in `rules.json` and wins |
+| `autoGraduate` | `on` | move `learn` to `notify` when the baseline is mature; never to `enforce` |
+
+## Try it safely
+
+1. Install it (it is not in any default bundle) and leave the mode at `learn`. Work as usual for a few days: it only learns.
+2. When it graduates to `notify`, read `/protector alerts` after each unattended run and `ack` the false positives.
+3. `/protector replay` shows what `enforce` would have blocked on your recent work. Only then consider `/protector mode enforce`.
+4. `ruflo-mods` with `modTrust = "refuse-risky"` refuses a mod that hooks `tool.check`: add `ruflo-protector@ruflo` to `modTrustAllow`.
+
+## Events and what is not covered
+
+Hooks: `tool.check` (every tool use; Bash, Write/Edit, WebFetch, MCP calls, SendMessage), `agent.spawn`, `session.receive` (peer messages, `PR-010`), `turn.start` / `turn.complete`, `session.start` / `session.end`, `command.run`. Not hooked, said plainly: the engine's `http.fetch` is a *plugin's* own request, not the model's, so model egress is seen through `tool.check` on WebFetch, WebSearch, network commands and remote MCP calls; `prompt.submit` is not used (the prompt for taint comparison comes from `turn.start`); a `tool.check` verdict that is `ask` is learned unless denied (the person approved or will decide). `PR-004` follows cred reads through Read/Bash only, `PR-007` counts `tool.check` calls per minute. The `files are a courtesy` rule: decisions use the mod's memory, never a file re-read mid-session, so editing `rules.json` or `allow.json` while a session runs changes nothing until the next session.
+
+## Performance
+
+`npx tsx plugins/ruflo-protector/scripts/bench.mjs`: median added cost per tool call is under 1 ms (budget); measured medians are 5 to 15 microseconds for ordinary calls and about 70 microseconds for a 200 KB write.
diff --git a/plugins/ruflo-protector/scripts/bench.mjs b/plugins/ruflo-protector/scripts/bench.mjs
new file mode 100644
index 0000000000..eb64a2a2d4
--- /dev/null
+++ b/plugins/ruflo-protector/scripts/bench.mjs
@@ -0,0 +1,69 @@
+/**
+ * Per-call cost of Project Anatole (ADR-453 section 12: median under 1 ms added per tool call).
+ *
+ * npx tsx plugins/ruflo-protector/scripts/bench.mjs [--iters 5000] [--json]
+ *
+ * Loads hooks/register.ts, chains its `tool.check` hooks like the engine does (a core that answers `allow`), and times the whole chain with a `$`
+ * whose ops resolve at once. The numbers are the mod's own cost: no Claude Code dispatch, no real I/O. Exit 1 when a median is over the budget.
+ */
+import { dirname, join, resolve } from 'node:path'
+import { performance } from 'node:perf_hooks'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+
+const arg = (n, d) => { const i = process.argv.indexOf(`--${n}`); return i > 0 ? process.argv[i + 1] : d }
+const ITERS = Number(arg('iters', 5000))
+const BUDGET_US = 1000
+const HERE = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+
+const special = { 'session.root': () => '/work', 'clock.now': () => 1_700_000_000_000 }
+const mk = (path) => new Proxy(function () {}, {
+ get: (_t, k) => (typeof k === 'string' ? mk(path ? `${path}.${k}` : k) : undefined),
+ apply: (_t, _this, args) => Promise.resolve(special[path]?.(...args) ?? (path.endsWith('read') ? Promise.reject(Object.assign(new Error('ENOENT'), { code: 'ENOENT' })) : undefined)),
+})
+const $ = mk('')
+
+function load(register, options) {
+ const regs = []
+ const on = (event, a, b) => {
+ const r = b ? { event, matcher: a, hook: b } : { event, hook: a }
+ regs.push(r)
+ return { catch: (h) => { r.onCatch = h } }
+ }
+ register(on, options)
+ return (event, e) => {
+ const chain = regs.filter((r) => r.event === event && (!r.matcher || Object.entries(r.matcher).every(([k, v]) => e[k] === v)))
+ const run = (i, ev) => (i >= chain.length ? Promise.resolve({ decision: 'allow' }) : chain[i].hook($, ev, (x) => run(i + 1, x)))
+ return run(0, e)
+ }
+}
+
+async function time(fn) {
+ for (let i = 0; i < 300; i++) await fn()
+ const s = new Float64Array(ITERS)
+ for (let i = 0; i < ITERS; i++) { const t = performance.now(); await fn(); s[i] = (performance.now() - t) * 1000 }
+ s.sort()
+ return { median: s[Math.floor(ITERS / 2)], p99: s[Math.floor(ITERS * 0.99)] }
+}
+
+const { register } = await import(pathToFileURL(join(HERE, 'hooks', 'register.ts')).href)
+const CASES = {
+ 'Read': { tool: 'Read', input: { file_path: '/work/src/index.ts' } },
+ 'Bash (git status)': { tool: 'Bash', input: { command: 'ls -la /work && git status --short' } },
+ 'Bash (curl, network)': { tool: 'Bash', input: { command: 'curl -s -d x=1 https://api.example.com/v1/items' } },
+ 'Write 200KB': { tool: 'Write', input: { file_path: '/work/src/big.txt', content: 'lorem ipsum dolor sit amet '.repeat(7500) } },
+}
+const out = {}
+for (const mode of ['learn', 'notify', 'enforce']) {
+ const dispatch = load(register, { mode })
+ await dispatch('session.start', { surface: 'terminal', isInteractive: true, cwd: '/work' })
+ out[mode] = {}
+ for (const [name, e] of Object.entries(CASES)) out[mode][name] = await time(() => dispatch('tool.check', e))
+}
+const worst = Math.max(...Object.values(out).flatMap((m) => Object.values(m).map((t) => t.median)))
+if (process.argv.includes('--json')) console.log(JSON.stringify({ iters: ITERS, budgetUs: BUDGET_US, worstMedianUs: worst, out }, null, 2))
+else {
+ console.log(`tool.check chain, median/p99 microseconds, ${ITERS} iterations (budget: median under ${BUDGET_US})`)
+ for (const [mode, m] of Object.entries(out)) for (const [name, t] of Object.entries(m)) console.log(`${mode.padEnd(8)} ${name.padEnd(22)} ${t.median.toFixed(1)} / ${t.p99.toFixed(1)}`)
+ console.log(`worst median: ${worst.toFixed(1)} us`)
+}
+process.exit(worst < BUDGET_US ? 0 : 1)
diff --git a/plugins/ruflo-protector/scripts/smoke.sh b/plugins/ruflo-protector/scripts/smoke.sh
new file mode 100755
index 0000000000..dd47fbf107
--- /dev/null
+++ b/plugins/ruflo-protector/scripts/smoke.sh
@@ -0,0 +1,64 @@
+#!/usr/bin/env bash
+# Structural smoke test for ruflo-protector v0.1.0, Project Anatole (ADR-453).
+set -u
+ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+PASS=0
+FAIL=0
+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 ruflo-protector 0.1.0 and names Project Anatole"
+grep -q '"name": "ruflo-protector"' "$ROOT/.claude-plugin/plugin.json" \
+ && grep -q '"version": "0.1.0"' "$ROOT/.claude-plugin/plugin.json" \
+ && grep -q 'Project Anatole' "$ROOT/.claude-plugin/plugin.json" && ok || bad "name/version/description"
+
+step "2. hooks.json names register.ts and every hook file is present and under 500 lines"
+mod_ok=1
+grep -q '"./register.ts"' "$ROOT/hooks/hooks.json" || mod_ok=0
+for f in options screen shapes rules baseline engine store scan command register rootdelete; do
+ [[ -f "$ROOT/hooks/$f.ts" ]] || mod_ok=0
+ [[ $(wc -l < "$ROOT/hooks/$f.ts" 2>/dev/null || echo 9999) -le 500 ]] || mod_ok=0
+done
+[[ $mod_ok -eq 1 ]] && ok || bad "mod hooks incomplete or too long"
+
+step "3. userConfig defaults are safe (mode learn, autoGraduate on; never enforce)"
+node -e '
+const c = require(process.argv[1]).userConfig || {}
+process.exit(c.mode && c.mode.default === "learn" && c.autoGraduate && c.autoGraduate.default === "on" ? 0 : 1)
+' "$ROOT/.claude-plugin/plugin.json" && ok || bad "userConfig defaults wrong"
+
+step "4. every userConfig option key has a README row"
+miss=""
+for k in $(node -e 'console.log(Object.keys(require(process.argv[1]).userConfig||{}).join(" "))' "$ROOT/.claude-plugin/plugin.json"); do
+ grep -qE "^\| \`$k\` \|" "$ROOT/README.md" || miss="$miss $k"
+done
+[[ -z "$miss" ]] && ok || bad "no README row for:$miss"
+
+step "5. hooks never touch the network or spawn a process"
+if grep -nE '\$\.(http|process)\.|child_process|fetch\(' "$ROOT"/hooks/*.ts >/dev/null; then bad "network or process call in hooks"; else ok; fi
+
+step "6. /protector is registered and collides with no command or skill of the plugin"
+if grep -q "name: 'protector'" "$ROOT/hooks/register.ts" && [[ ! -e "$ROOT/commands/protector.md" && ! -e "$ROOT/skills/protector" ]]; then ok; else bad "command name missing or taken"; fi
+
+step "7. the catalogue has all 13 rules and the README lists every /protector verb"
+miss=""
+for i in 01 02 03 04 05 06 07 08 09 10 11 12 13; do grep -q "'PR-0$i'" "$ROOT/hooks/rules.ts" || miss="$miss PR-0$i"; done
+for v in status list rule mode run replay alerts ack unack allow reset-baseline; do grep -q "\`$v" "$ROOT/README.md" || miss="$miss verb:$v"; done
+[[ -z "$miss" ]] && ok || bad "missing:$miss"
+
+step "8. the corpus has at least 20 benign traces and an attack trace per rule"
+b=$(grep -cE "^ '[a-z0-9-]+': \[" "$ROOT/tests/corpus/benign.ts")
+miss=""
+for i in 01 02 03 04 05 06 07 08 09 10 11 12 13; do grep -q "'PR-0$i-" "$ROOT/tests/corpus/attacks.ts" || miss="$miss PR-0$i"; done
+[[ $b -ge 20 && -z "$miss" ]] && ok || bad "benign=$b attacks missing:$miss"
+
+step "9. kit tests pass (claude plugin test)"
+if command -v claude >/dev/null 2>&1; then
+ out=$(claude plugin test "$ROOT" 2>&1); echo "$out" | grep -qE ' 0 fail' && ok || bad "$(echo "$out" | tail -3 | tr '\n' ' ')"
+else
+ printf "SKIP (claude not on PATH)\n"
+fi
+
+printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
+[[ $FAIL -eq 0 ]] || exit 1