@heretek-ai/epistemic-swarm 0.4.3 → 0.4.4

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "High-Integrity Dialectic Research Agent Harness for Claude Code enforcing empirical evidence over parametric hallucination.",
   "author": {
     "name": "Heretek AI",

package/install.sh

@@ -177,6 +177,31 @@ try:
             print(f"   + Added agent: {name}")
         else:
             print(f"   ℹ️ Agent already configured: {name}")
+
+    # Skills: snippet paths are repo-relative ("./skills/x") which breaks
+    # from ~/.config — merge as absolute paths, repairing relative entries.
+    import os as _os
+    wanted = []
+    for sp in snippet.get("skills", {}).get("paths", []):
+        wanted.append(sp if _os.path.isabs(sp) else str(repo / sp.lstrip("./")))
+    skills_cfg = cfg.setdefault("skills", {})
+    paths = skills_cfg.setdefault("paths", [])
+    # Repair repo-relative entries in place, then append missing absolutes.
+    for i, existing in enumerate(list(paths)):
+        for abs_sp in wanted:
+            if existing == abs_sp:
+                break
+            rel = "./" + str(Path(abs_sp).relative_to(repo)) if str(abs_sp).startswith(str(repo)) else None
+            if rel and existing == rel:
+                paths[i] = abs_sp
+                print(f"   ~ Repaired relative skill path: {rel} -> {abs_sp}")
+                break
+    for abs_sp in wanted:
+        if abs_sp not in paths:
+            paths.append(abs_sp)
+            print(f"   + Added skill path: {abs_sp}")
+        else:
+            print(f"   ℹ️ Skill path already configured: {abs_sp}")
 except Exception as e:
     print(f"   ⚠️ Non-critical warning merging agents: {e}")
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@heretek-ai/epistemic-swarm",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "IUMBTEMS: I Use My Brain To Express My Self — High-Integrity Dialectic Research Agent Harness for Claude Code, OpenCode V2, Pi, OMP (oh-my-pi), Gemini CLI, Codex CLI, and AntiGravity",
   "main": "bin/cli.js",
   "bin": {

package/plugins/antigravity/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://antigravity.google/schemas/v1/plugin.json",
   "name": "epistemic-swarm",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for AntiGravity.",
   "author": "Heretek AI",
   "license": "Apache-2.0",

package/plugins/gemini/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "epistemic-swarm",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "description": "IUMBTEMS Epistemic Swarm: dialectic research, code audit, OSS scout, and lateral brainstorming for Gemini CLI.",
   "mcpServers": {
     "brave-search": {

package/plugins/opencode/index.js

@@ -11,7 +11,7 @@
  * catalog. Schemas mirror runner/mcp_server.py build_tools() — keep in sync.
  */
 
-import { spawnSync } from 'child_process';
+import { spawn } from 'child_process';
 import { readFileSync } from 'fs';
 import path from 'path';
 import { fileURLToPath } from 'url';
@@ -30,21 +30,40 @@ try {
   // keep fallback; version is informational only
 }
 
-/** Uniform dispatch: one-shot MCP call, return OpenCode's {content, status}. */
+/**
+ * Uniform dispatch: one-shot MCP call, return OpenCode's {content, status}.
+ * Async (non-blocking spawn) so long swarms/audits never freeze the host
+ * event loop; cancellation remains the host's prerogative.
+ */
 function callMcp(tool, args = {}, cwd) {
-  const res = spawnSync(
-    'python3',
-    [MCP_SERVER, 'call', tool, JSON.stringify(args || {})],
-    {
-      encoding: 'utf-8',
-      cwd: cwd || process.cwd(),
-      env: { ...process.env, PYTHONPATH: PKG_ROOT },
+  return new Promise((resolve) => {
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    const done = (content, status) => {
+      if (settled) return;
+      settled = true;
+      resolve({ content, status });
+    };
+    let child;
+    try {
+      child = spawn(
+        'python3',
+        [MCP_SERVER, 'call', tool, JSON.stringify(args || {})],
+        {
+          cwd: cwd || process.cwd(),
+          env: { ...process.env, PYTHONPATH: PKG_ROOT },
+        }
+      );
+    } catch (err) {
+      done(String((err && err.message) || err), 'error');
+      return;
     }
-  );
-  return {
-    content: res.stdout || res.stderr,
-    status: res.status === 0 ? 'success' : 'error',
-  };
+    child.stdout.on('data', (d) => { stdout += String(d); });
+    child.stderr.on('data', (d) => { stderr += String(d); });
+    child.on('error', (err) => done(String((err && err.message) || err), 'error'));
+    child.on('close', (code) => done(stdout || stderr, code === 0 ? 'success' : 'error'));
+  });
 }
 
 /** Catalog mirrors runner/mcp_server.py build_tools(). */
@@ -351,9 +370,11 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'swarm',
     description: 'Run IUMBTEMS dialectic research swarm on an objective',
+    usage: '/swarm <objective>',
     template: [
       'Run an IUMBTEMS dialectic research swarm.',
       'Objective: $ARGUMENTS',
+      'If $ARGUMENTS is empty, ask the user for the research objective first; never call the tool with placeholder, empty, or literal "<objective>" arguments.',
       '1. If the objective is ambiguous, frame it first via iumbtems_socratic_frontier.',
       '2. Execute iumbtems_swarm_research with {"objective": "<objective>"} (pass "mock_mode": true only for dry runs).',
       '3. Summarize .research/final_synthesis.md, preserving [VERIFIED:<hash>] pointers.',
@@ -362,6 +383,7 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'grill',
     description: 'Launch Socratic grilling and decision tree frontier exploration',
+    usage: '/grill [--objective <text>]',
     template: [
       'Launch Socratic grilling on the decision frontier.',
       'Objective: $ARGUMENTS (may be empty to inspect the current frontier)',
@@ -372,6 +394,7 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'swarm-config',
     description: 'Inspect or update Epistemic Swarm parameters (engine, depth, mode)',
+    usage: '/swarm-config [--engine <e>] [--depth <d>] [--mode <m>] [--show]',
     template: [
       'Inspect or update the Epistemic Swarm configuration.',
       'Arguments: $ARGUMENTS (may be empty to inspect current settings)',
@@ -381,9 +404,11 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'audit',
     description: 'Run dialectic codebase architectural and security audit with line-level proof',
+    usage: '/audit <target_path_or_scope>',
     template: [
       'Run an IUMBTEMS dialectic codebase audit (structural architect vs adversarial red-teamer).',
       'Target: $ARGUMENTS (path, component, or empty for full-repository architecture and vulnerability audit)',
+      'If $ARGUMENTS names a path that does not exist, ask the user to clarify the target first; never audit a placeholder path.',
       '1. Execute iumbtems_code_audit with {"target": "<target>"} (pass "mock_mode": true only for dry runs).',
       '2. Summarize .research/code_audit_report.md with line-level proof pointers.',
     ].join('\n'),
@@ -391,9 +416,11 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'scout',
     description: 'Scout open-source libraries, audit copyleft licenses, generate clean-room blueprints',
+    usage: '/scout <feature_or_algorithm>',
     template: [
       'Scout open-source solutions for the requested capability.',
       'Feature: $ARGUMENTS',
+      'If $ARGUMENTS is empty, ask the user for the feature or algorithm first; never call the tool with placeholder, empty, or literal "<feature>" arguments.',
       '1. Execute iumbtems_oss_scout with {"feature": "<feature>"} (pass "mock_mode": true only for dry runs).',
       '2. Report mature candidates, GPL/AGPL copyleft risks, and the clean-room blueprint in .research/oss_scout_report.md.',
     ].join('\n'),
@@ -401,6 +428,7 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'brainstorming',
     description: 'Lateral brainstorming: novel feature vectors, paradigm inversions, falsifiable spikes',
+    usage: '/brainstorming <ambiguous-prompt>',
     template: [
       'Run lateral brainstorming (divergent what-if ideation, never bug-fix lists).',
       'Prompt: $ARGUMENTS (defaults to "Where do we go from here?" when empty)',
@@ -411,6 +439,7 @@ export const OPENCODE_COMMANDS = [
   {
     name: 'brainstorm',
     description: 'Alias for /brainstorming',
+    usage: '/brainstorm <ambiguous-prompt>',
     template: [
       'Alias for /brainstorming: run lateral brainstorming (divergent what-if ideation, never bug-fix lists).',
       'Prompt: $ARGUMENTS (defaults to "Where do we go from here?" when empty)',
@@ -640,7 +669,7 @@ export function createOpenCodePlugin(context = {}) {
           updates.divergence_threshold = opts.divergence_threshold;
         }
         if (Object.keys(updates).length > 0) {
-          callMcp('iumbtems_config', updates, appContext?.cwd);
+          await callMcp('iumbtems_config', updates, appContext?.cwd);
         }
       }
       // Phase C: idle staleness nudge (opt out with {staleness_nudge: false}).

package/plugins/opencode/tui.js

@@ -15,6 +15,7 @@ import { readFileSync, readdirSync, statSync } from 'fs';
 import path from 'path';
 import { createElement, insert, setProp } from '@opentui/solid';
 import { createEffect, createSignal, onCleanup } from 'solid-js';
+import { OPENCODE_COMMANDS } from './index.js';
 
 const PLUGIN_ID = 'heretek.iumbtems.epistemic-swarm.tui';
 const REFRESH_MS = 5000;
@@ -172,26 +173,47 @@ function SwarmSidebar(api, root, sessionID) {
 }
 
 function SwarmKeymapLayer(api) {
+  const toast = (title, message) => {
+    try {
+      api.ui.toast.show({ title, message, variant: 'info', duration: 4000 });
+    } catch {
+      /* toast is best-effort */
+    }
+  };
+  const commands = [
+    {
+      id: 'iumbtems.swarm-status',
+      title: 'Swarm status',
+      description: 'Show IUMBTEMS workspace status (mode, reports, frontier, STALE claims)',
+      group: 'IUMBTEMS',
+      palette: true,
+      run: () => {
+        const root = resolveRoot(api);
+        toast('IUMBTEMS', summarize(readSwarmStatus(root)));
+      },
+    },
+  ];
+  // Every slash command gets a palette entry (usage toast; the host has no
+  // programmatic slash-invoke API, so discovery + usage guidance is the win).
+  for (const cmd of OPENCODE_COMMANDS || []) {
+    if (!cmd || !cmd.name) continue;
+    commands.push({
+      id: `iumbtems.command.${cmd.name}`,
+      title: `/${cmd.name}`,
+      description: cmd.description || cmd.name,
+      group: 'IUMBTEMS',
+      palette: true,
+      run: () => {
+        toast(
+          `IUMBTEMS /${cmd.name}`,
+          `${cmd.usage || cmd.description || ''} — type /${cmd.name} in the prompt to run.`
+        );
+      },
+    });
+  }
   api.keymap.layer(() => ({
     mode: 'global',
-    commands: [
-      {
-        id: 'iumbtems.swarm-status',
-        title: 'Swarm status',
-        description: 'Show IUMBTEMS workspace status (mode, reports, frontier, STALE claims)',
-        group: 'IUMBTEMS',
-        palette: true,
-        run: () => {
-          const root = resolveRoot(api);
-          api.ui.toast.show({
-            title: 'IUMBTEMS',
-            message: summarize(readSwarmStatus(root)),
-            variant: 'info',
-            duration: 4000,
-          });
-        },
-      },
-    ],
+    commands,
   }));
   return null;
 }

package/runner/tests/test_bet1_spike.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python3
+"""CI-safe tests for the Bet-1 advisory spike harness (no LLM, no network)."""
+
+import json
+import subprocess
+import sys
+import tempfile
+import unittest
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent.parent
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+from scripts.bet1_advisory_spike import (  # noqa: E402
+    advisory_comment,
+    generate,
+    score_fixture,
+)
+
+
+class TestBet1Harness(unittest.TestCase):
+    def test_generate_counts_and_layout(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            manifest = generate(Path(tmp))
+            self.assertEqual(len(manifest), 20)
+            defective = [e for e in manifest if not e["clean"]]
+            clean = [e for e in manifest if e["clean"]]
+            self.assertEqual(len(defective), 16)
+            self.assertEqual(len(clean), 4)
+            for entry in manifest:
+                self.assertTrue((Path(tmp) / entry["id"] / entry["file"]).exists())
+
+    def test_generate_deterministic(self):
+        with tempfile.TemporaryDirectory() as t1, tempfile.TemporaryDirectory() as t2:
+            m1 = generate(Path(t1))
+            m2 = generate(Path(t2))
+            self.assertEqual(m1, m2)
+
+    def test_scorer_hit_and_tolerance(self):
+        entry = {"id": "x", "file": "users.py", "line": 6, "clean": False}
+        self.assertTrue(score_fixture(entry, "see users.py:6 SQLi")["hit"])
+        self.assertTrue(score_fixture(entry, "users.py L8 concat")["hit"])
+        self.assertFalse(score_fixture(entry, "users.py:40 unrelated")["hit"])
+        self.assertFalse(score_fixture(entry, "no file cited")["hit"])
+
+    def test_scorer_clean_flags_fp(self):
+        entry = {"id": "c", "file": "util.py", "line": None, "clean": True}
+        self.assertTrue(score_fixture(entry, "issue in util.py:2")["false_positive"])
+        self.assertFalse(
+            score_fixture(entry, "all clear, nothing found")["false_positive"]
+        )
+
+    def test_advisory_is_non_blocking_shape(self):
+        comment = advisory_comment("bet1-01", "findings text")
+        self.assertIn("non-blocking", comment)
+        self.assertIn("bet1-01", comment)
+        self.assertIn("findings text", comment)
+
+    def test_cli_generate_and_score_exit_zero(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            for argv in (["--generate", "--dir", tmp], ["--score", "--dir", tmp]):
+                res = subprocess.run(
+                    [
+                        sys.executable,
+                        str(PROJECT_ROOT / "scripts" / "bet1_advisory_spike.py"),
+                    ]
+                    + argv,
+                    capture_output=True,
+                    text=True,
+                    timeout=120,
+                )
+                self.assertEqual(res.returncode, 0, res.stderr)
+            summary = json.loads(
+                subprocess.run(
+                    [
+                        sys.executable,
+                        str(PROJECT_ROOT / "scripts" / "bet1_advisory_spike.py"),
+                        "--score",
+                        "--dir",
+                        tmp,
+                    ],
+                    capture_output=True,
+                    text=True,
+                    timeout=120,
+                ).stdout
+            )
+            self.assertEqual(summary["fixtures"], 20)
+            # No advisories written yet -> all misses, no false positives.
+            self.assertEqual(summary["hits"], 0)
+            self.assertEqual(summary["false_positives"], 0)
+
+
+if __name__ == "__main__":
+    unittest.main()

package/runner/tests/test_opencode_ux.py

@@ -75,6 +75,39 @@ class TestOpenCodeCommandCatalog(unittest.TestCase):
             self.assertIn(c, data["registered"])
             self.assertTrue(data["templates"][c])
 
+    def test_empty_arg_guards(self):
+        res = run_node(
+            """
+            import { OPENCODE_COMMANDS } from "./plugins/opencode/index.js";
+            const guarded = OPENCODE_COMMANDS.filter(c => /empty/i.test(c.template) && /ask the user/i.test(c.template)).map(c => c.name);
+            const withUsage = OPENCODE_COMMANDS.filter(c => !!c.usage).map(c => c.name);
+            console.log(JSON.stringify({guarded, withUsage, total: OPENCODE_COMMANDS.length}));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"guard test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        for c in ["swarm", "scout", "audit"]:
+            self.assertIn(c, data["guarded"])
+        self.assertEqual(len(data["withUsage"]), data["total"])
+
+    def test_async_execute_resolves(self):
+        res = run_node(
+            """
+            import plugin from "./plugins/opencode/index.js";
+            const shell = await plugin.server();
+            let ticked = false;
+            const timer = setInterval(() => { ticked = true; }, 5);
+            const r = await shell.tool.iumbtems_config.execute({});
+            clearInterval(timer);
+            console.log(JSON.stringify({status: r.status, hasContent: typeof r.content === "string" && r.content.length > 0, loopAlive: ticked}));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"async execute test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        self.assertEqual(data["status"], "success")
+        self.assertTrue(data["hasContent"])
+        self.assertTrue(data["loopAlive"])
+
     def test_registration_never_overwrites(self):
         res = run_node(
             """
@@ -180,6 +213,13 @@ class TestInstallOpenCode(unittest.TestCase):
             cmd = cfg["mcp"]["iumbtems"]["command"]
             self.assertTrue(Path(cmd[-1]).is_absolute())
             self.assertEqual(cmd[-1], str(PROJECT_ROOT / "runner" / "mcp_server.py"))
+            # Skills merged as absolute repo paths (relative entries repaired).
+            skill_paths = cfg.get("skills", {}).get("paths", [])
+            self.assertTrue(skill_paths)
+            for sp in skill_paths:
+                self.assertTrue(Path(sp).is_absolute(), f"relative skill path: {sp}")
+            self.assertIn(str(PROJECT_ROOT / "skills" / "grilling"), skill_paths)
+            self.assertFalse(any(not Path(sp).is_absolute() for sp in skill_paths))
             # Second run changes nothing.
             before = oc_path.read_bytes()
             second = self._run_install(home)
@@ -285,6 +325,42 @@ class TestOpenCodeTui(unittest.TestCase):
             self.assertEqual(data["suspect"], 1)
             self.assertEqual(data["requeued"], 2)
 
+    def test_palette_entries_for_all_commands(self):
+        res = run_node(
+            """
+            import { setupTui } from "./plugins/opencode/tui.js";
+            import { OPENCODE_COMMANDS } from "./plugins/opencode/index.js";
+            const renders = [];
+            let factory = null;
+            const toasts = [];
+            const mock = {
+              theme: {}, directory: process.cwd(),
+              ui: { slot: (arg) => { renders.push(arg); return () => {}; }, toast: { show: (t) => toasts.push(t) }, router: { current: () => ({type: "other"}) } },
+              keymap: { layer: (fn) => { factory = fn; } }
+            };
+            setupTui(mock);
+            const appSlot = renders.find(r => r && r.append === "app");
+            if (!appSlot) throw new Error("app slot not registered");
+            appSlot.render();
+            const spec = factory();
+            const palette = spec.commands.filter(c => c.palette);
+            for (const c of palette) c.run();
+            console.log(JSON.stringify({
+              total: spec.commands.length,
+              palette: palette.length,
+              groups: [...new Set(palette.map(c => c.group))],
+              toasts: toasts.length,
+              expected: OPENCODE_COMMANDS.length + 1
+            }));
+            """
+        )
+        self.assertEqual(res.returncode, 0, f"palette test failed: {res.stderr}")
+        data = last_json_object(res.stdout)
+        self.assertEqual(data["total"], data["expected"])
+        self.assertEqual(data["palette"], data["expected"])
+        self.assertEqual(data["groups"], ["IUMBTEMS"])
+        self.assertEqual(data["toasts"], data["expected"])
+
 
 class TestOpenCodeLifecycle(unittest.TestCase):
     @staticmethod

package/scripts/bet1_advisory_spike.py

@@ -0,0 +1,426 @@
+#!/usr/bin/env python3
+"""Bet-1 advisory spike: proof-carrying review on a synthetic PR fixture set.
+
+Advisory mode ONLY: findings are formatted as PR comments, never block, and
+the process always exits 0. Measures: seeded-defect hit rate (finding cites
+seeded file + line within +/-3) and clean-fixture false-positive rate.
+
+  python3 scripts/bet1_advisory_spike.py --generate --dir /tmp/bet1
+  python3 scripts/bet1_advisory_spike.py --run --mock --dir /tmp/bet1
+  python3 scripts/bet1_advisory_spike.py --run --live --only bet1-01,bet1-02 --dir /tmp/bet1
+  python3 scripts/bet1_advisory_spike.py --score --dir /tmp/bet1
+
+Live runs invoke real audits (LLM spend); mock runs exercise dispatch only.
+"""
+
+import argparse
+import json
+import re
+import subprocess
+import sys
+from pathlib import Path
+
+PROJECT_ROOT = Path(__file__).resolve().parent.parent
+LINE_TOLERANCE = 3
+
+# name -> (filename, lines, seeded_line_1based, description)
+FIXTURES = {
+    "hardcoded-secret-1": (
+        "auth.py",
+        [
+            'API_KEY = "sk-live-51H7x9Q2mZ4v8K3n"  # production key',
+            "",
+            "def headers():",
+            '    return {"Authorization": f"Bearer {API_KEY}"}',
+        ],
+        1,
+        "hardcoded production secret",
+    ),
+    "hardcoded-secret-2": (
+        "config.py",
+        [
+            "import os",
+            "",
+            'DB_PASSWORD = "P@ssw0rd-2024-prod"',
+            "",
+            "def dsn():",
+            '    return f"postgres://admin:{DB_PASSWORD}@db:5432/app"',
+        ],
+        3,
+        "hardcoded database password",
+    ),
+    "sqli-concat-1": (
+        "users.py",
+        [
+            "import sqlite3",
+            "",
+            "def get_user(db, username):",
+            "    conn = sqlite3.connect(db)",
+            "    cur = conn.cursor()",
+            '    query = "SELECT * FROM users WHERE name = \'" + username + "\'"',
+            "    cur.execute(query)",
+            "    return cur.fetchall()",
+        ],
+        6,
+        "SQL string concatenation with user input",
+    ),
+    "sqli-concat-2": (
+        "orders.py",
+        [
+            "import sqlite3",
+            "",
+            "def get_orders(db, status, limit):",
+            "    conn = sqlite3.connect(db)",
+            "    sql = f\"SELECT * FROM orders WHERE status='{status}' LIMIT {limit}\"",
+            "    return conn.execute(sql).fetchall()",
+        ],
+        5,
+        "f-string SQL with user input",
+    ),
+    "race-counter-1": (
+        "counter.py",
+        [
+            "import threading",
+            "",
+            "total = 0",
+            "",
+            "def add(n):",
+            "    global total",
+            "    total += n",
+            "",
+            "threads = [threading.Thread(target=add, args=(i,)) for i in range(100)]",
+            "[t.start() for t in threads]",
+        ],
+        7,
+        "unsynchronized shared counter across threads",
+    ),
+    "race-counter-2": (
+        "cache.py",
+        [
+            "import threading",
+            "",
+            "_cache = {}",
+            "",
+            "def get_or_load(key, loader):",
+            "    if key not in _cache:",
+            "        _cache[key] = loader()",
+            "    return _cache[key]",
+        ],
+        7,
+        "check-then-act race on shared dict",
+    ),
+    "auth-bypass-1": (
+        "login.py",
+        [
+            "def is_admin(user):",
+            "    return True",
+            "",
+            "def delete_account(user, target):",
+            "    if is_admin(user):",
+            "        return db.delete(target)",
+            "    raise PermissionError()",
+        ],
+        2,
+        "authorization check always returns True",
+    ),
+    "auth-bypass-2": (
+        "views.py",
+        [
+            "def admin_panel(request):",
+            '    if request.args.get("debug") == "1":',
+            "        return render_admin()",
+            "    if not request.user or not request.user.is_staff:",
+            "        abort(403)",
+            "    return render_admin()",
+        ],
+        2,
+        "debug query param bypasses staff check",
+    ),
+    "off-by-one-1": (
+        "paging.py",
+        [
+            "def page(items, n, size):",
+            "    start = n * size",
+            "    return items[start:start + size + 1]",
+        ],
+        3,
+        "page slice returns size+1 items",
+    ),
+    "off-by-one-2": (
+        "retry.py",
+        [
+            "def fetch_with_retry(url, tries=3):",
+            "    for i in range(tries + 1):",
+            "        try:",
+            "            return http_get(url)",
+            "        except NetError:",
+            "            continue",
+            "    raise GiveUp()",
+        ],
+        2,
+        "loop runs tries+1 attempts, not tries",
+    ),
+    "exec-input-1": (
+        "render.py",
+        [
+            "def render(template_name, context):",
+            '    expr = "f\'" + open(template_name).read() + "\'"',
+            "    return eval(expr, {}, context)",
+        ],
+        3,
+        "eval on template file content with context",
+    ),
+    "exec-input-2": (
+        "calc.py",
+        [
+            "def calculate(formula, variables):",
+            '    return eval(formula, {"__builtins__": {}}, variables)',
+        ],
+        2,
+        "eval on user-supplied formula string",
+    ),
+    "weak-crypto-1": (
+        "passwords.py",
+        [
+            "import hashlib",
+            "",
+            "def store_pw(username, password):",
+            "    digest = hashlib.md5(password.encode()).hexdigest()",
+            "    db.save(username, digest)",
+        ],
+        4,
+        "MD5 for password hashing, no salt",
+    ),
+    "weak-crypto-2": (
+        "tokens.py",
+        [
+            "import random",
+            "",
+            "def new_token():",
+            '    return "%016x" % random.getrandbits(64)',
+        ],
+        4,
+        "Mersenne Twister for security tokens",
+    ),
+    "path-traversal-1": (
+        "files.py",
+        [
+            "import os",
+            "",
+            'BASE = "/srv/uploads"',
+            "",
+            "def read_upload(name):",
+            "    with open(os.path.join(BASE, name)) as f:",
+            "        return f.read()",
+        ],
+        6,
+        "unsanitized join allows ../ escape",
+    ),
+    "path-traversal-2": (
+        "export.py",
+        [
+            "import os",
+            "import shutil",
+            "",
+            "def export_report(name, dest_dir):",
+            '    src = os.path.join("/srv/reports", name)',
+            "    return shutil.copy(src, dest_dir)",
+        ],
+        5,
+        "unsanitized report name allows ../ escape",
+    ),
+}
+
+CLEAN_FIXTURES = {
+    "clean-1": (
+        "util.py",
+        [
+            "def clamp(value, lo, hi):",
+            "    return max(lo, min(hi, value))",
+        ],
+        "no defect: pure bounds clamp",
+    ),
+    "clean-2": (
+        "queries.py",
+        [
+            "import sqlite3",
+            "",
+            "def get_user(db, username):",
+            "    conn = sqlite3.connect(db)",
+            "    return conn.execute(",
+            '        "SELECT * FROM users WHERE name = ?", (username,)',
+            "    ).fetchall()",
+        ],
+        "no defect: parameterized query",
+    ),
+    "clean-3": (
+        "authn.py",
+        [
+            "import hashlib",
+            "import hmac",
+            "import secrets",
+            "",
+            "def check(password, stored):",
+            '    digest = hashlib.pbkdf2_hmac("sha256", password.encode(), stored["salt"], 600_000)',
+            '    return hmac.compare_digest(digest, stored["digest"])',
+        ],
+        "no defect: salted KDF with constant-time compare",
+    ),
+    "clean-4": (
+        "counter_safe.py",
+        [
+            "import threading",
+            "",
+            "_lock = threading.Lock()",
+            "total = 0",
+            "",
+            "def add(n):",
+            "    global total",
+            "    with _lock:",
+            "        total += n",
+        ],
+        "no defect: locked counter",
+    ),
+}
+
+
+def generate(root):
+    root = Path(root)
+    manifest = []
+    for fid, (fname, lines, line, desc) in FIXTURES.items():
+        d = root / fid
+        d.mkdir(parents=True, exist_ok=True)
+        d.joinpath(fname).write_text("\n".join(lines) + "\n", encoding="utf-8")
+        manifest.append(
+            {
+                "id": fid,
+                "file": fname,
+                "line": line,
+                "class": fid.rsplit("-", 1)[0],
+                "defect": desc,
+                "clean": False,
+            }
+        )
+    for fid, (fname, lines, desc) in CLEAN_FIXTURES.items():
+        d = root / fid
+        d.mkdir(parents=True, exist_ok=True)
+        d.joinpath(fname).write_text("\n".join(lines) + "\n", encoding="utf-8")
+        manifest.append(
+            {
+                "id": fid,
+                "file": fname,
+                "line": None,
+                "class": "clean",
+                "defect": desc,
+                "clean": True,
+            }
+        )
+    root.joinpath("manifest.json").write_text(
+        json.dumps(manifest, indent=2), encoding="utf-8"
+    )
+    print(f"generated {len(manifest)} fixtures in {root}")
+    return manifest
+
+
+def run_audit(target_dir, mock, timeout=600):
+    """Invoke the real dispatch path. Advisory: findings only, never blocks."""
+    args = {"target": str(target_dir)}
+    if mock:
+        args["mock_mode"] = True
+    proc = subprocess.run(
+        [
+            sys.executable,
+            str(PROJECT_ROOT / "runner" / "mcp_server.py"),
+            "call",
+            "iumbtems_code_audit",
+            json.dumps(args),
+        ],
+        capture_output=True,
+        text=True,
+        timeout=timeout,
+        cwd=str(PROJECT_ROOT),
+    )
+    return proc.stdout + proc.stderr
+
+
+def advisory_comment(fixture_id, findings):
+    return (
+        f"### IUMBTEMS advisory review: `{fixture_id}`\n\n"
+        f"Automated findings below are **non-blocking**. Verify each cited line before acting.\n\n"
+        f"{findings}\n"
+    )
+
+
+LINE_RE = re.compile(r"(?:^|[\s(:\[\"'])(?:line\s+)?L?(\d{1,4})\b", re.IGNORECASE)
+
+
+def score_fixture(entry, findings):
+    """Hit = seeded filename cited with a line number within tolerance."""
+    if entry["clean"]:
+        cited_own_file = entry["file"] in findings
+        return {"hit": False, "false_positive": cited_own_file}
+    if entry["file"] not in findings:
+        return {"hit": False, "false_positive": False}
+    lines = {int(n) for n in LINE_RE.findall(findings)}
+    hit = any(abs(n - entry["line"]) <= LINE_TOLERANCE for n in lines)
+    return {"hit": hit, "false_positive": False}
+
+
+def score_all(root):
+    manifest = json.loads((Path(root) / "manifest.json").read_text(encoding="utf-8"))
+    results = []
+    for entry in manifest:
+        comment_file = Path(root) / entry["id"] / "advisory.md"
+        findings = (
+            comment_file.read_text(encoding="utf-8") if comment_file.exists() else ""
+        )
+        results.append({"id": entry["id"], **score_fixture(entry, findings)})
+    defective = [r for r, e in zip(results, manifest) if not e["clean"]]
+    clean = [r for r, e in zip(results, manifest) if e["clean"]]
+    hits = sum(1 for r in defective if r["hit"])
+    fps = sum(1 for r in clean if r["false_positive"])
+    return {
+        "fixtures": len(manifest),
+        "defective": len(defective),
+        "hits": hits,
+        "hit_rate": round(hits / max(len(defective), 1), 3),
+        "false_positives": fps,
+        "clean_total": len(clean),
+        "misses": [r["id"] for r in defective if not r["hit"]],
+        "results": results,
+    }
+
+
+def main(argv=None):
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--dir", default="/tmp/bet1")
+    ap.add_argument("--generate", action="store_true")
+    ap.add_argument("--run", action="store_true")
+    ap.add_argument("--score", action="store_true")
+    ap.add_argument("--mock", action="store_true")
+    ap.add_argument("--live", action="store_true")
+    ap.add_argument("--only", default="")
+    args = ap.parse_args(argv)
+    root = Path(args.dir)
+
+    if args.generate or (not args.run and not args.score):
+        generate(root)
+    if args.run:
+        manifest = json.loads((root / "manifest.json").read_text(encoding="utf-8"))
+        only = {s.strip() for s in args.only.split(",") if s.strip()}
+        for entry in manifest:
+            if only and entry["id"] not in only:
+                continue
+            findings = run_audit(root / entry["id"], mock=args.mock and not args.live)
+            (root / entry["id"] / "advisory.md").write_text(
+                advisory_comment(entry["id"], findings), encoding="utf-8"
+            )
+            print(f"advisory written: {entry['id']}")
+    if args.score:
+        summary = score_all(root)
+        print(json.dumps(summary, indent=2))
+    return 0  # advisory: never blocks
+
+
+if __name__ == "__main__":
+    sys.exit(main())