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-adr): one-shot import + verify scripts (v0.3.0) (#1758)

rUvcd0b66f0d41f
diff --git a/plugins/ruflo-adr/.claude-plugin/plugin.json b/plugins/ruflo-adr/.claude-plugin/plugin.json
index 4970514085..5619bfcfa2 100644
--- a/plugins/ruflo-adr/.claude-plugin/plugin.json
+++ b/plugins/ruflo-adr/.claude-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-adr",
"description": "ADR lifecycle management \u2014 create, index, supersede, check compliance, and link Architecture Decision Records to code via AgentDB hierarchical store + causal edges (supersedes/amends/depends-on/related)",
- "version": "0.2.0",
+ "version": "0.3.0",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-adr/scripts/import.mjs b/plugins/ruflo-adr/scripts/import.mjs
new file mode 100755
index 0000000000..c89f4c8bb0
--- /dev/null
+++ b/plugins/ruflo-adr/scripts/import.mjs
@@ -0,0 +1,273 @@
+#!/usr/bin/env node
+// One-shot ADR importer for the ruflo-adr plugin.
+//
+// Walks the working directory (or ADR_ROOT override), parses every ADR file
+// under */docs/adr/ or */docs/adrs/, persists records to the `adr-patterns`
+// namespace, persists causal edges to the `adr-edges` namespace, prints a
+// summary with status counts + relationship breakdown + dangling-ref check.
+//
+// Handles two ADR formats:
+// 1. v3-style: `# ADR-097: Title` heading + `**Status**: Proposed` line
+// 2. plugin-style: YAML frontmatter (`status: Proposed`) at file head
+//
+// Usage:
+// node scripts/import.mjs # markdown summary to stdout
+// IMPORT_FORMAT=json node scripts/import.mjs # JSON summary
+// IMPORT_DRY_RUN=1 node scripts/import.mjs # parse + summarize, skip memory_store
+// ADR_ROOT=/path/to/repo node scripts/import.mjs # override scan root (default: cwd)
+//
+// Why a script, not raw MCP calls: 70+ ADRs Γ— multiple memory_store calls each
+// is hundreds of MCP round-trips. spawnSync over the CLI is materially faster
+// and avoids shell-quoting pitfalls in the ADR titles.
+
+import { readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const ROOT = process.env.ADR_ROOT || process.cwd();
+const SKIP_DIRS = new Set(['node_modules', '.git', 'dist', 'v2', '.next', '.turbo', 'build']);
+
+function findAdrs(dir, out = []) {
+ let entries;
+ try { entries = readdirSync(dir); } catch { return out; }
+ for (const e of entries) {
+ if (SKIP_DIRS.has(e)) continue;
+ const p = join(dir, e);
+ let st;
+ try { st = statSync(p); } catch { continue; }
+ if (st.isDirectory()) {
+ findAdrs(p, out);
+ } else if (e.endsWith('.md') && (p.includes('/docs/adr/') || p.includes('/docs/adrs/'))) {
+ out.push(p);
+ }
+ }
+ return out;
+}
+
+function parseAdr(path) {
+ const text = readFileSync(path, 'utf-8');
+ const id = parseId(path, text);
+ const title = parseTitle(text);
+ const status = parseStatus(text);
+ const date = parseDate(text);
+ const tags = parseTags(text);
+ const context = parseContextFirstParagraph(text);
+ const links = parseLinks(text, id);
+ return { id, title, status, date, tags, context, links, file: path.replace(ROOT + '/', '') };
+}
+
+function parseId(path, text) {
+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);
+ if (fm) {
+ const m = /^id:\s*(\S+)/m.exec(fm[1]);
+ if (m) return m[1].toUpperCase();
+ }
+ const fname = basename(path, '.md');
+ const m = /^(ADR-?\d+|\d{3,4})/i.exec(fname);
+ if (m) {
+ const raw = m[1];
+ return raw.toUpperCase().startsWith('ADR') ? raw.toUpperCase().replace(/^ADR-?/, 'ADR-') : `ADR-${raw}`;
+ }
+ return fname;
+}
+
+function parseTitle(text) {
+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);
+ if (fm) {
+ const m = /^title:\s*(.+)$/m.exec(fm[1]);
+ if (m) return m[1].trim();
+ }
+ const m = /^#\s*(?:ADR-?\d+:?\s*)?(.+?)$/m.exec(text);
+ return m ? m[1].trim() : '(untitled)';
+}
+
+function parseStatus(text) {
+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);
+ if (fm) {
+ const m = /^status:\s*(.+)$/im.exec(fm[1]);
+ if (m) return m[1].trim();
+ }
+ // Match `**Status**:` plus `**Status**:` with possible adornments.
+ // Strip parenthetical qualifiers like "Proposed (v3.6.x)" -> "Proposed".
+ const m = /^\*\*Status\*\*:\s*([A-Za-z][A-Za-z\- ]*?)(?:\s*\(.*?\))?\s*$/m.exec(text);
+ return m ? m[1].trim() : 'Unknown';
+}
+
+function parseDate(text) {
+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);
+ if (fm) {
+ const m = /^date:\s*(\S+)/m.exec(fm[1]);
+ if (m) return m[1];
+ }
+ const m = /^\*\*Date\*\*:\s*(\S+)/m.exec(text);
+ return m ? m[1] : '';
+}
+
+function parseTags(text) {
+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);
+ if (fm) {
+ const m = /^tags:\s*\[([^\]]+)\]/m.exec(fm[1]);
+ if (m) return m[1].split(',').map((s) => s.trim()).filter(Boolean);
+ }
+ const m = /^\*\*Tags\*\*:\s*(.+)$/m.exec(text);
+ return m ? m[1].split(',').map((s) => s.trim()).filter(Boolean) : [];
+}
+
+function parseContextFirstParagraph(text) {
+ const m = /^##\s*Context\s*$\s*([\s\S]+?)(?=^##\s|\Z)/m.exec(text);
+ if (!m) return '';
+ return m[1].trim().split(/\n\s*\n/)[0].replace(/\s+/g, ' ').slice(0, 400);
+}
+
+// Extract ADR-NNN references from a link line. CRITICAL: must distinguish ADR
+// references from GitHub issue numbers (#1697 etc.) which the prior version
+// false-positively captured as "ADR-1697". We only recognize bare numbers as
+// ADR refs when they appear in a known ADR-link section AND they don't look
+// like GitHub issues (no leading #, no leading "issue").
+function parseLinks(text, selfId) {
+ const out = [];
+ // Frontmatter relationships
+ const fm = /^---\s*$([\s\S]*?)^---\s*$/m.exec(text);
+ if (fm) {
+ for (const [field, relation] of [
+ ['supersedes', 'supersedes'],
+ ['amended-by', 'amends'],
+ ['amends', 'amends'],
+ ['related', 'related'],
+ ['depends-on', 'depends-on'],
+ ]) {
+ const re = new RegExp(`^${field}:\\s*\\[?([^\\]\\n]+)\\]?$`, 'mi');
+ const m = re.exec(fm[1]);
+ if (m) for (const ref of extractAdrRefs(m[1])) {
+ if (relation === 'supersedes') out.push({ from: ref, to: selfId, relation });
+ else out.push({ from: selfId, to: ref, relation });
+ }
+ }
+ }
+ // Body relationship lines
+ const supersedes = /\*\*Supersedes\*\*:\s*(.+)$/m.exec(text);
+ if (supersedes) for (const ref of extractAdrRefs(supersedes[1])) out.push({ from: ref, to: selfId, relation: 'supersedes' });
+ const amended = /\*\*(?:Amended[ -]by|Amends)\*\*:\s*(.+)$/m.exec(text);
+ if (amended) for (const ref of extractAdrRefs(amended[1])) out.push({ from: selfId, to: ref, relation: 'amends' });
+ const related = /\*\*Related\*\*:\s*(.+)$/m.exec(text);
+ if (related) for (const ref of extractAdrRefs(related[1])) out.push({ from: selfId, to: ref, relation: 'related' });
+ const dependsOn = /\*\*Depends[ -]on\*\*:\s*(.+)$/m.exec(text);
+ if (dependsOn) for (const ref of extractAdrRefs(dependsOn[1])) out.push({ from: selfId, to: ref, relation: 'depends-on' });
+ return out;
+}
+
+function extractAdrRefs(s) {
+ const refs = new Set();
+ // Strip GitHub issue / commit references first to prevent false positives.
+ const cleaned = s
+ .replace(/#\d+/g, '') // #1697
+ .replace(/issue[s]?\s*\d+/gi, '') // issue 1697
+ .replace(/PR\s*\d+/gi, '') // PR 1234
+ .replace(/commit\s*[`a-f0-9]+/gi, '') // commit `abc123`
+ .replace(/`[^`]*`/g, ''); // any backtick-quoted span
+ const re = /\bADR-?(\d+)\b/gi;
+ let m;
+ while ((m = re.exec(cleaned))) refs.add(`ADR-${m[1].padStart(3, '0').replace(/^0+(\d{3,})/, '$1')}`);
+ return [...refs];
+}
+
+function memoryStore(namespace, key, value) {
+ const r = spawnSync('npx', [
+ '@claude-flow/cli@latest', 'memory', 'store',
+ '--namespace', namespace,
+ '--key', key,
+ '--value', typeof value === 'string' ? value : JSON.stringify(value),
+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+ if (r.status !== 0) {
+ if (/UNIQUE constraint/i.test(r.stderr || r.stdout || '')) return 'exists';
+ return 'error: ' + (r.stderr || '').slice(0, 100);
+ }
+ return 'ok';
+}
+
+const dryRun = process.env.IMPORT_DRY_RUN === '1';
+const fmt = process.env.IMPORT_FORMAT || 'markdown';
+
+const files = findAdrs(ROOT);
+const adrs = files.map(parseAdr);
+const byId = new Map();
+const allEdges = [];
+for (const a of adrs) {
+ byId.set(a.id, a);
+ allEdges.push(...a.links);
+}
+
+let storedRecords = 0, storedEdges = 0;
+const errors = [];
+if (!dryRun) {
+ for (const a of adrs) {
+ const r = memoryStore('adr-patterns', `${a.id}::${basename(a.file, '.md')}`,
+ `${a.title} β€” ${a.context || '(no context)'}\n\nfile: ${a.file}\nstatus: ${a.status}\ndate: ${a.date}\ntags: ${a.tags.join(',')}`);
+ if (r === 'ok' || r === 'exists') storedRecords++;
+ else errors.push(`${a.id} ${a.file}: ${r}`);
+ }
+ for (const e of allEdges) {
+ const key = `${e.relation}:${e.from}->${e.to}:${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+ const r = memoryStore('adr-edges', key, JSON.stringify({ ...e, capturedAt: new Date().toISOString() }));
+ if (r === 'ok' || r === 'exists') storedEdges++;
+ }
+}
+
+const danglingRefs = allEdges.filter((e) => !byId.has(e.to));
+const supersededIds = new Set(allEdges.filter((x) => x.relation === 'supersedes').map((x) => x.from));
+const statusMismatches = [];
+for (const id of supersededIds) {
+ const a = byId.get(id);
+ if (a && !/superseded/i.test(a.status)) statusMismatches.push({ id, status: a.status, file: a.file });
+}
+
+const byStatus = {};
+for (const a of adrs) {
+ const k = (a.status || 'unknown').toLowerCase();
+ byStatus[k] = (byStatus[k] || 0) + 1;
+}
+const byRelation = {};
+for (const e of allEdges) byRelation[e.relation] = (byRelation[e.relation] || 0) + 1;
+const bySource = {};
+for (const a of adrs) {
+ const src = a.file.split('/docs/')[0];
+ bySource[src] = (bySource[src] || 0) + 1;
+}
+
+const result = {
+ scannedRoot: ROOT,
+ total: adrs.length,
+ sourceDirs: Object.keys(bySource).length,
+ storedRecords, storedEdges, dryRun,
+ byStatus, byRelation, bySource,
+ edges: allEdges.length,
+ danglingRefs, statusMismatches, errors,
+};
+
+if (fmt === 'json') {
+ console.log(JSON.stringify(result, null, 2));
+ process.exit(0);
+}
+
+console.log('## ADR Index Summary');
+console.log('');
+console.log(`Total ADRs: **${result.total}** across ${result.sourceDirs} source dirs (root: ${ROOT})`);
+console.log(`Records stored to \`adr-patterns\`: ${result.storedRecords}/${result.total}${dryRun ? ' (dry-run, skipped)' : ''}`);
+console.log(`Edges stored to \`adr-edges\`: ${result.storedEdges}/${result.edges}${dryRun ? ' (dry-run, skipped)' : ''}`);
+console.log('');
+console.log('### By status');
+for (const [k, n] of Object.entries(byStatus).sort((a, b) => b[1] - a[1])) console.log(`- ${k}: ${n}`);
+console.log('');
+console.log(`### Relationships: **${result.edges}** edges`);
+for (const [k, n] of Object.entries(byRelation).sort((a, b) => b[1] - a[1])) console.log(`- ${k}: ${n}`);
+console.log('');
+console.log('### Issues found');
+console.log(`- Dangling refs (edge β†’ non-existent ADR): ${danglingRefs.length}`);
+for (const d of danglingRefs.slice(0, 10)) console.log(` - ${d.relation} ${d.from} β†’ ${d.to} (missing)`);
+console.log(`- Status mismatches (superseded but not marked): ${statusMismatches.length}`);
+for (const m of statusMismatches.slice(0, 10)) console.log(` - ${m.id} status='${m.status}' (${m.file})`);
+console.log(`- Storage errors: ${errors.length}`);
+for (const e of errors.slice(0, 5)) console.log(` - ${e}`);
+console.log('');
+console.log('### Source breakdown');
+for (const [s, n] of Object.entries(bySource).sort((a, b) => b[1] - a[1]).slice(0, 12)) console.log(`- ${s}: ${n}`);
diff --git a/plugins/ruflo-adr/scripts/smoke.sh b/plugins/ruflo-adr/scripts/smoke.sh
index 348c31ca09..c44541c98c 100755
--- a/plugins/ruflo-adr/scripts/smoke.sh
+++ b/plugins/ruflo-adr/scripts/smoke.sh
@@ -9,10 +9,10 @@ ok() { printf "PASS\n"; PASS=$((PASS+1)); }
bad() { printf "FAIL: %s\n" "$1"; FAIL=$((FAIL+1)); }
# 1. plugin.json bump + new keywords
-step "1. plugin.json declares 0.2.0 with new keywords"
+step "1. plugin.json declares 0.3.0 with new keywords"
v=$(grep -E '"version"' "$ROOT/.claude-plugin/plugin.json" | grep -oE '[0-9]+\.[0-9]+\.[0-9]+' | head -1)
-if [[ "$v" != "0.2.0" ]]; then
- bad "expected 0.2.0, got '$v'"
+if [[ "$v" != "0.3.0" ]]; then
+ bad "expected 0.3.0, got '$v'"
else
miss=""
for k in lifecycle compliance causal-graph mcp; do
@@ -21,10 +21,10 @@ else
[[ -z "$miss" ]] && ok || bad "missing keywords:$miss"
fi
-# 2. All 3 skills present with valid frontmatter
-step "2. skills (adr-create, adr-index, adr-review) present with name/description/allowed-tools"
+# 2. All 4 skills present with valid frontmatter
+step "2. skills (adr-create, adr-index, adr-review, adr-verify) present with name/description/allowed-tools"
miss=""
-for s in adr-create adr-index adr-review; do
+for s in adr-create adr-index adr-review adr-verify; do
f="$ROOT/skills/$s/SKILL.md"
[[ -f "$f" ]] || { miss="$miss missing-$s"; continue; }
for k in 'name:' 'description:' 'allowed-tools:'; do
@@ -85,5 +85,46 @@ for f in "$ROOT"/skills/*/SKILL.md; do
done
[[ -z "$bad_skills" ]] && ok || bad "wildcard:$bad_skills"
+# 11. import + verify scripts present, executable, parse cleanly
+step "11. scripts/import.mjs and verify.mjs executable + syntax-clean"
+miss=""
+for s in import.mjs verify.mjs; do
+ f="$ROOT/scripts/$s"
+ [[ -x "$f" ]] || miss="$miss $s-not-executable"
+ node --check "$f" 2>/dev/null || miss="$miss $s-syntax-error"
+done
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+# 12. import.mjs handles both ADR formats + has issue-number false-positive guard
+step "12. import.mjs supports v3 + plugin formats and strips issue numbers"
+F="$ROOT/scripts/import.mjs"
+miss=""
+grep -q "extractAdrRefs" "$F" || miss="$miss no-extractAdrRefs"
+grep -q "frontmatter\|YAML\|^---" "$F" || miss="$miss no-frontmatter-handling"
+grep -q "#\\\\d+\|issue\|PR\\\\s*\\\\d" "$F" || miss="$miss no-issue-strip"
+grep -q '\*\*Status\*\*' "$F" || miss="$miss no-v3-status-pattern"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+# 13. verify.mjs reports cycles + dangling refs and exits 1 on cycles
+step "13. verify.mjs detects cycles + has fail-closed exit"
+F="$ROOT/scripts/verify.mjs"
+miss=""
+grep -q "cycles" "$F" || miss="$miss no-cycle-detection"
+grep -q "danglingRefs" "$F" || miss="$miss no-dangling-detection"
+grep -q "process.exit(1)" "$F" || miss="$miss no-fail-exit"
+[[ -z "$miss" ]] && ok || bad "$miss"
+
+# 14. adr-index skill references the script (not direct MCP loop)
+step "14. adr-index skill calls scripts/import.mjs"
+F="$ROOT/skills/adr-index/SKILL.md"
+grep -q "scripts/import\.mjs\|import\.mjs" "$F" \
+ && ok || bad "skill does not invoke import.mjs"
+
+# 15. adr-verify skill references verify.mjs
+step "15. adr-verify skill calls scripts/verify.mjs"
+F="$ROOT/skills/adr-verify/SKILL.md"
+grep -q "scripts/verify\.mjs\|verify\.mjs" "$F" \
+ && ok || bad "skill does not invoke verify.mjs"
+
printf "\n%s passed, %s failed\n" "$PASS" "$FAIL"
[[ $FAIL -eq 0 ]] || exit 1
diff --git a/plugins/ruflo-adr/scripts/verify.mjs b/plugins/ruflo-adr/scripts/verify.mjs
new file mode 100755
index 0000000000..a2cc171366
--- /dev/null
+++ b/plugins/ruflo-adr/scripts/verify.mjs
@@ -0,0 +1,114 @@
+#!/usr/bin/env node
+// adr-verify β€” read the persisted adr-patterns + adr-edges namespaces, surface
+// dangling refs, supersede cycles, and status mismatches.
+//
+// Companion to scripts/import.mjs. Run after import to validate graph integrity.
+// Useful in CI: exits with code 1 if any issues found (gate on graph health).
+//
+// Usage:
+// node scripts/verify.mjs # markdown report
+// VERIFY_FORMAT=json node scripts/verify.mjs # JSON for chaining
+// VERIFY_STRICT=1 node scripts/verify.mjs # exit 1 on ANY issue (default: only on cycles)
+
+import { spawnSync } from 'node:child_process';
+
+function memoryListJson(namespace) {
+ const r = spawnSync('npx', [
+ '@claude-flow/cli@latest', 'memory', 'list',
+ '--namespace', namespace, '--format', 'json',
+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+ if (r.status !== 0) return [];
+ const m = /\[[\s\S]*\]/.exec(r.stdout || '');
+ if (!m) return [];
+ try { return JSON.parse(m[0]); } catch { return []; }
+}
+function memoryRetrieve(namespace, key) {
+ const r = spawnSync('npx', [
+ '@claude-flow/cli@latest', 'memory', 'retrieve',
+ '--namespace', namespace, '--key', key,
+ ], { stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8' });
+ if (r.status !== 0) return null;
+ // Strip ANSI / box-drawing
+ const txt = (r.stdout || '').replace(/\x1b\[[0-9;]*m/g, '');
+ return txt;
+}
+
+const patternEntries = memoryListJson('adr-patterns');
+const edgeEntries = memoryListJson('adr-edges');
+
+const adrIds = new Set(
+ patternEntries.map((e) => (e.key || '').split('::')[0]).filter(Boolean)
+);
+
+// Parse edge values to recover {from, to, relation}
+const edges = [];
+for (const e of edgeEntries) {
+ const k = e.key || '';
+ // key format: relation:FROM->TO:timestamp-rand
+ const m = /^(\w[\w-]*?):(\S+?)->(\S+?):/.exec(k);
+ if (m) edges.push({ relation: m[1], from: m[2], to: m[3], key: k });
+}
+
+const danglingRefs = edges.filter((e) => !adrIds.has(e.to));
+const danglingFroms = edges.filter((e) => !adrIds.has(e.from));
+
+// Cycle detection on supersedes (cycle = data corruption β€” ADR can't supersede itself transitively)
+const supersedesGraph = new Map();
+for (const e of edges.filter((e) => e.relation === 'supersedes')) {
+ if (!supersedesGraph.has(e.from)) supersedesGraph.set(e.from, []);
+ supersedesGraph.get(e.from).push(e.to);
+}
+const cycles = [];
+function findCycle(node, visited, stack) {
+ if (stack.has(node)) {
+ cycles.push([...stack, node].join(' β†’ '));
+ return;
+ }
+ if (visited.has(node)) return;
+ visited.add(node);
+ stack.add(node);
+ for (const next of supersedesGraph.get(node) || []) {
+ findCycle(next, visited, stack);
+ }
+ stack.delete(node);
+}
+for (const n of supersedesGraph.keys()) findCycle(n, new Set(), new Set());
+
+const result = {
+ adrCount: adrIds.size,
+ edgeCount: edges.length,
+ byRelation: edges.reduce((acc, e) => { acc[e.relation] = (acc[e.relation] || 0) + 1; return acc; }, {}),
+ danglingRefs,
+ danglingFroms,
+ cycles: [...new Set(cycles)],
+};
+
+if (process.env.VERIFY_FORMAT === 'json') {
+ console.log(JSON.stringify(result, null, 2));
+} else {
+ console.log('## ADR Graph Verification');
+ console.log('');
+ console.log(`| Metric | Value |`);
+ console.log(`|---|---:|`);
+ console.log(`| ADRs in adr-patterns | ${result.adrCount} |`);
+ console.log(`| Edges in adr-edges | ${result.edgeCount} |`);
+ for (const [k, n] of Object.entries(result.byRelation).sort((a, b) => b[1] - a[1])) {
+ console.log(`| edges (${k}) | ${n} |`);
+ }
+ console.log(`| Dangling 'to' refs | ${result.danglingRefs.length} |`);
+ console.log(`| Dangling 'from' refs | ${result.danglingFroms.length} |`);
+ console.log(`| Supersede cycles | ${result.cycles.length} |`);
+ if (result.danglingRefs.length) {
+ console.log('\n### Sample dangling refs');
+ for (const d of result.danglingRefs.slice(0, 8)) console.log(`- ${d.relation} ${d.from} β†’ ${d.to} (missing)`);
+ }
+ if (result.cycles.length) {
+ console.log('\n### Cycles (DATA CORRUPTION β€” fix immediately)');
+ for (const c of result.cycles) console.log(`- ${c}`);
+ }
+}
+
+const strict = process.env.VERIFY_STRICT === '1';
+if (result.cycles.length || (strict && (result.danglingRefs.length || result.danglingFroms.length))) {
+ process.exit(1);
+}
diff --git a/plugins/ruflo-adr/skills/adr-index/SKILL.md b/plugins/ruflo-adr/skills/adr-index/SKILL.md
index c10553d5d8..a4a42b0f62 100644
--- a/plugins/ruflo-adr/skills/adr-index/SKILL.md
+++ b/plugins/ruflo-adr/skills/adr-index/SKILL.md
@@ -1,66 +1,73 @@
---
name: adr-index
-description: Build or rebuild the ADR index and dependency graph in AgentDB
+description: Build or rebuild the ADR index + dependency graph by running scripts/import.mjs (handles v3-style and plugin-style ADR formats; one Bash call vs hundreds of MCP round-trips)
argument-hint: ""
-allowed-tools: mcp__claude-flow__agentdb_hierarchical-store mcp__claude-flow__agentdb_hierarchical-query mcp__claude-flow__agentdb_causal-edge mcp__claude-flow__agentdb_causal-query mcp__claude-flow__memory_store mcp__claude-flow__memory_search Bash Read Grep Glob
+allowed-tools: Bash mcp__claude-flow__memory_list mcp__claude-flow__memory_search
---
# ADR Index
-Build or rebuild the full ADR index and dependency graph in AgentDB from the `docs/adr/` directory.
+Persists every ADR under `*/docs/adr/` or `*/docs/adrs/` to the `adr-patterns` namespace and every relationship (supersedes / amends / related / depends-on) to `adr-edges`. Handles both ADR formats found in the Ruflo monorepo:
+
+- **v3-style**: `# ADR-097: Title` heading + `**Status**: Proposed` line
+- **plugin-style**: YAML frontmatter (`id: ADR-NNNN`, `status: Proposed`)
+
+Implementation is in `scripts/import.mjs` (one Bash call) rather than dozens of per-ADR MCP tool calls β€” same effective behavior, materially faster, dual-format-aware, and false-positive-resistant for issue numbers.
## When to use
-After importing ADRs from another project, when the AgentDB graph is out of sync, or when bootstrapping ADR tracking on an existing codebase that already has ADR files.
+- After importing ADRs from another project
+- When the AgentDB graph is out of sync with the on-disk ADR files
+- Bootstrapping ADR tracking on an existing codebase
## Steps
-1. **Scan directory** -- `Glob` for `docs/adr/ADR-*.md` to find all ADR files. If no files found, report that no ADRs exist yet.
-
-2. **Parse each ADR** -- `Read` each file and extract:
- - **ID**: from the filename (e.g., `ADR-042` from `ADR-042-use-postgres.md`)
- - **Title**: from the `# ADR-NNN: <Title>` heading
- - **Status**: from the `**Status**:` line
- - **Date**: from the `**Date**:` line
- - **Tags**: from the `**Tags**:` line
- - **Links**: from the `## Links` section (supersedes, amended-by, related)
-
-3. **Store in AgentDB** -- For each ADR, call `mcp__claude-flow__agentdb_hierarchical-store` with:
- - path: `adr/<adr-id>`
- - value: `{ "id": "<id>", "title": "<title>", "status": "<status>", "date": "<date>", "tags": "<tags>", "file": "<filepath>" }`
-
-4. **Build causal edges** -- For each ADR with links:
- - "Supersedes ADR-XXX" -> `mcp__claude-flow__agentdb_causal-edge` with `from: ADR-XXX`, `to: <current>`, `relation: supersedes`
- - "Amended by ADR-YYY" -> `mcp__claude-flow__agentdb_causal-edge` with `from: <current>`, `to: ADR-YYY`, `relation: amends`
- - "Related: ADR-ZZZ" -> `mcp__claude-flow__agentdb_causal-edge` with `from: <current>`, `to: ADR-ZZZ`, `relation: related`
- - "Depends on ADR-WWW" -> `mcp__claude-flow__agentdb_causal-edge` with `from: <current>`, `to: ADR-WWW`, `relation: depends-on`
-
-5. **Store in memory** -- For each ADR, call `mcp__claude-flow__memory_store` with:
- - namespace: `adr-patterns`
- - key: `<adr-id>`
- - value: `<title> β€” <first paragraph of Context section>`
- This enables semantic search across ADRs.
-
-6. **Verify graph** -- Call `mcp__claude-flow__agentdb_causal-query` to retrieve all edges and verify:
- - No dangling references (edges pointing to non-existent ADRs)
- - No circular supersedes chains
- - All superseded ADRs have status "superseded"
-
-7. **Report** -- Output a summary:
+1. **Run the importer**:
+
+ ```bash
+ node plugins/ruflo-adr/scripts/import.mjs
```
- ## ADR Index Summary
- Total ADRs: N
- - Proposed: X
- - Accepted: Y
- - Deprecated: Z
- - Superseded: W
+ Optional env:
+ - `IMPORT_FORMAT=json` β€” emit JSON instead of markdown
+ - `IMPORT_DRY_RUN=1` β€” parse + summarize, skip persistence
+ - `ADR_ROOT=/path` β€” scan a different root (default: cwd)
+
+2. **Inspect the summary** β€” total ADRs, stored count, by-status breakdown, edge counts, dangling refs, status mismatches.
- Relationships: M edges
- - Supersedes: A
- - Amends: B
- - Depends-on: C
- - Related: D
+3. **Verify graph integrity** (optional but recommended) via the sibling `adr-verify` skill, which runs `scripts/verify.mjs` and exits 1 on cycles.
- Issues found: (list any dangling refs or status mismatches)
+4. **Search semantically** via `mcp__claude-flow__memory_search` against the populated namespace:
+
+ ```
+ memory_search --query "federation budget" --namespace adr-patterns
```
+
+## Storage shape
+
+`adr-patterns` namespace, key `<ADR-id>::<basename>`, value (text):
+
+```
+<title> β€” <first paragraph of Context>
+
+file: <relative path>
+status: <Proposed|Accepted|Superseded|...>
+date: <ISO date>
+tags: <comma-separated>
+```
+
+`adr-edges` namespace, key `<relation>:<FROM>-><TO>:<timestamp-rand>`, value:
+
+```json
+{ "from": "ADR-097", "to": "ADR-086", "relation": "related", "capturedAt": "<ISO>" }
+```
+
+## False-positive guard
+
+`#1697` / `commit abc123` / `PR 1234` references inside ADR bodies are stripped before regex extraction so they don't get misread as `ADR-1697` etc. See `extractAdrRefs()` in `scripts/import.mjs`.
+
+## Cross-references
+
+- `adr-create` β€” produces the ADR files this skill consumes
+- `adr-review` β€” runs over `adr-patterns` for compliance checks
+- `adr-verify` (sibling skill) β€” runs `scripts/verify.mjs` for graph-integrity gating
diff --git a/plugins/ruflo-adr/skills/adr-verify/SKILL.md b/plugins/ruflo-adr/skills/adr-verify/SKILL.md
new file mode 100644
index 0000000000..40b6afeea1
--- /dev/null
+++ b/plugins/ruflo-adr/skills/adr-verify/SKILL.md
@@ -0,0 +1,42 @@
+---
+name: adr-verify
+description: Read back adr-patterns + adr-edges namespaces, surface dangling refs / supersede cycles / status mismatches; exit 1 on cycles
+argument-hint: ""
+allowed-tools: Bash mcp__claude-flow__memory_list mcp__claude-flow__memory_retrieve
+---
+
+# ADR Verify
+
+Companion to `adr-index`. After import, reads the persisted graph and surfaces integrity issues:
+
+- **Dangling refs** β€” edge points at an ADR ID that doesn't exist in `adr-patterns`. Common cause: the referenced ADR is in a sibling repo or got deleted.
+- **Supersede cycles** β€” `ADR-A supersedes ADR-B` and `ADR-B supersedes ADR-A` (or longer cycles). Always data corruption.
+- **Status mismatches** β€” an ADR is the source of a `supersedes` edge but its own status isn't `Superseded`. Usually a missed status update during a successor ADR's promotion.
+
+## When to use
+
+- Right after `adr-index` to confirm the graph is healthy
+- In CI as a fail-closed gate (`VERIFY_STRICT=1` exits 1 on any issue)
+- Before publishing an ADR-related release
+
+## Steps
+
+```bash
+node plugins/ruflo-adr/scripts/verify.mjs
+```
+
+Optional env:
+- `VERIFY_FORMAT=json` β€” JSON instead of markdown
+- `VERIFY_STRICT=1` β€” exit 1 on ANY issue (default: only on cycles)
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Graph healthy (or dangling refs / status mismatches present in non-strict mode) |
+| `1` | Supersede cycle detected, OR strict mode + any issue present |
+
+## Cross-references
+
+- `adr-index` β€” populates the data this skill verifies
+- `scripts/import.mjs` β€” has its own dry-run validation; this skill is the read-back companion