Skip to content

armgit / ruflo

Public Imported from GitHub
0

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

fix(ruflo-adr): read the leading status keyword, skip index/template files, report Unknown in adr-verify (#4126)

r08fa73eadbdb
diff --git a/plugins/ruflo-adr/.claude-plugin/plugin.json b/plugins/ruflo-adr/.claude-plugin/plugin.json
index 7397fa327f..da625709a3 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 β€” create, index, reconcile, supersede, check compliance, and link Architecture Decision Records to code via AgentDB hierarchical store + causal edges (supersedes/amends/depends-on/related)",
- "version": "0.5.7",
+ "version": "0.5.8",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-adr/.codex-plugin/plugin.json b/plugins/ruflo-adr/.codex-plugin/plugin.json
index 8945f87052..bf346b839c 100644
--- a/plugins/ruflo-adr/.codex-plugin/plugin.json
+++ b/plugins/ruflo-adr/.codex-plugin/plugin.json
@@ -1,7 +1,7 @@
{
"name": "ruflo-adr",
"description": "ADR lifecycle management \u2014 create, index, reconcile, supersede, check compliance, and link Architecture Decision Records to code via AgentDB hierarchical store + causal edges (supersedes/amends/depends-on/related)",
- "version": "0.5.7",
+ "version": "0.5.8",
"author": {
"name": "ruvnet",
"url": "https://github.com/ruvnet"
diff --git a/plugins/ruflo-adr/CHANGELOG.md b/plugins/ruflo-adr/CHANGELOG.md
index 35b68ec7c1..7a28c0f6a0 100644
--- a/plugins/ruflo-adr/CHANGELOG.md
+++ b/plugins/ruflo-adr/CHANGELOG.md
@@ -2,6 +2,9 @@
Newest first. One `## <version> β€” <date>` heading per version, then `feat:`, `fix:`, `breaking:` and `chore:` bullets (ADR-478). Built from git history; older versions: `git log -- plugins/ruflo-adr`.
+## 0.5.8 β€” 2026-10-14
+- fix: the ADR parser reads the leading status keyword, so `superseded by [ADR-025](…) (date)`, `accepted (date) β€” note` and `Accepted (date) Β· **AMENDED …**` are no longer indexed as Unknown (adr-review enforces only accepted ADRs, so those ADRs were being skipped); `superseded by ADR-X` now records the supersedes edge; README.md, index.md and template*.md files in docs/adr are no longer indexed as ADRs; `adr-verify` reports any ADR left at Unknown (exit 1 under VERIFY_STRICT=1) (#4126, thanks @ronmikailov)
+
## 0.5.7 β€” 2026-10-12
- fix: the shared text screen now catches `.env` and e-mailed credentials, no longer flags a model's token talk (`--max-tokens`, `/oauth/token`, "token usage"), and no longer flags values that only name where a secret lives (`./service-account.json`, `--set-secrets=NAME=NAME:latest`); every rule stays linear (#4094, thanks @proffesor-for-testing)
diff --git a/plugins/ruflo-adr/README.md b/plugins/ruflo-adr/README.md
index 48aac9e8de..42beedcf12 100644
--- a/plugins/ruflo-adr/README.md
+++ b/plugins/ruflo-adr/README.md
@@ -25,7 +25,7 @@ claude --plugin-dir plugins/ruflo-adr
| `adr-create` | `/adr-create <title>` | Create a new ADR with sequential numbering and AgentDB registration |
| `adr-index` | `/adr-index` | Build or rebuild the ADR index and dependency graph in AgentDB (add/update only β€” never removes) |
| `adr-review` | `/adr-review [--branch BRANCH]` | Review code changes against accepted ADRs for compliance violations |
-| `adr-verify` | `/adr-verify` | Read back adr-patterns + adr-edges namespaces, surface dangling refs / supersede cycles / status mismatches; exits 1 on cycles |
+| `adr-verify` | `/adr-verify` | Read back adr-patterns + adr-edges namespaces, surface dangling refs / supersede cycles / Unknown statuses; exits 1 on cycles |
| `adr-reindex` | `/adr-reindex` | Reconcile a **deleted** ADR file: drop-and-rebuild adr-patterns + adr-edges from what's on disk right now |
## Commands (7 subcommands)
diff --git a/plugins/ruflo-adr/scripts/__tests__/adr-status-forms-4126.test.mjs b/plugins/ruflo-adr/scripts/__tests__/adr-status-forms-4126.test.mjs
new file mode 100644
index 0000000000..c4cec55474
--- /dev/null
+++ b/plugins/ruflo-adr/scripts/__tests__/adr-status-forms-4126.test.mjs
@@ -0,0 +1,91 @@
+// #4126: real-world status lines must not fall to "Unknown", README-style index files
+// are not ADRs, and `adr-verify` surfaces any ADR left at Unknown.
+import assert from 'node:assert/strict';
+import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+
+import { findAdrs, parseAdr } from '../lib/parse-adrs.mjs';
+import { unknownStatusIds } from '../lib/index-records.mjs';
+
+function withAdrs(files, fn) {
+ const root = mkdtempSync(join(tmpdir(), 'ruflo-adr-4126-'));
+ try {
+ const dir = join(root, 'docs', 'adr');
+ mkdirSync(dir, { recursive: true });
+ for (const [name, body] of Object.entries(files)) writeFileSync(join(dir, name), body);
+ return fn(root, dir);
+ } finally {
+ rmSync(root, { recursive: true, force: true });
+ }
+}
+
+const adr = (n, statusLine, extra = '') => `# ADR-${n}: Decision ${n}\n\n${statusLine}\n- **Date**: 2026-07-02\n${extra}\n## Context\n\nSomething.\n`;
+
+test('status keyword is read from the start of the line, whatever follows it', () => {
+ const cases = [
+ ['- **Status**: superseded by [ADR-025](ADR-025-next.md) (2026-07-02)', 'superseded'],
+ ['- **Status**: accepted (2026-07-02) β€” de-risking spike closed all items', 'accepted'],
+ ['**Status:** Accepted (2026-08-18) Β· **AMENDED 2026-08-20 β€” see Amendment 1 for the details**', 'Accepted'],
+ ['- **Status**: accepted', 'accepted'],
+ ['**Status**: Proposed (v3.6.x)', 'Proposed'],
+ ['**Status:** Deprecated, replaced by ADR-040', 'Deprecated'],
+ ['- **Status**: Rejected β€” not needed', 'Rejected'],
+ ];
+ withAdrs(Object.fromEntries(cases.map(([line], i) => [`ADR-${100 + i}-x.md`, adr(100 + i, line)])), (root, dir) => {
+ cases.forEach(([line, want], i) => {
+ const parsed = parseAdr(join(dir, `ADR-${100 + i}-x.md`), root);
+ assert.equal(parsed.status, want, `status line: ${line}`);
+ });
+ });
+});
+
+test('existing forms keep their result: frontmatter status, multi-word status, no status', () => {
+ withAdrs({
+ 'ADR-200-fm.md': '---\nid: ADR-200\nstatus: accepted\n---\n# ADR-200: fm\n',
+ 'ADR-201-multi.md': adr(201, '- **Status**: In Progress'),
+ 'ADR-202-none.md': '# ADR-202: nothing\n\nNo status line here.\n',
+ }, (root, dir) => {
+ assert.equal(parseAdr(join(dir, 'ADR-200-fm.md'), root).status, 'accepted');
+ assert.equal(parseAdr(join(dir, 'ADR-201-multi.md'), root).status, 'In Progress');
+ assert.equal(parseAdr(join(dir, 'ADR-202-none.md'), root).status, 'Unknown');
+ });
+});
+
+test('"superseded by ADR-X" in the status line records the superseding ADR', () => {
+ withAdrs({
+ 'ADR-009-old.md': adr(9, '- **Status**: superseded by [ADR-025](ADR-025-new.md) (2026-07-02)'),
+ }, (root, dir) => {
+ const parsed = parseAdr(join(dir, 'ADR-009-old.md'), root);
+ assert.deepEqual(
+ parsed.links.map(({ from, to, relation }) => `${relation}:${from}->${to}`),
+ ['supersedes:ADR-009->ADR-025'],
+ );
+ });
+});
+
+test('index and template files in docs/adr are not ADRs', () => {
+ withAdrs({
+ 'README.md': '# Architecture decisions\n\n| ADR | Title |\n|---|---|\n| 1 | x |\n',
+ 'index.md': '# Index\n',
+ 'template.md': '# ADR-000: template\n',
+ 'template-madr.md': '# ADR-000: template\n',
+ 'ADR-001-real.md': adr(1, '- **Status**: accepted'),
+ }, (root) => {
+ const found = findAdrs(root).map((p) => p.split('/').pop());
+ assert.deepEqual(found, ['ADR-001-real.md']);
+ });
+});
+
+test('unknownStatusIds lists the ADRs the importer could not classify', () => {
+ const value = (status) => `Title β€” Context.\n\nfile: docs/adr/x.md\nstatus: ${status}\ndate: 2026-07-02\ntags: a`;
+ const entries = [
+ { key: 'ADR-001::accepted', value: value('accepted') },
+ { key: 'ADR-002::b', value: value('Unknown') },
+ { key: 'ADR-003::c', value: value('unknown') },
+ { key: 'ADR-004::d', value: 'no status line at all' },
+ { key: 'ADR-005::e' },
+ ];
+ assert.deepEqual(unknownStatusIds(entries), ['ADR-002', 'ADR-003']);
+});
diff --git a/plugins/ruflo-adr/scripts/lib/index-records.mjs b/plugins/ruflo-adr/scripts/lib/index-records.mjs
index c073dee7a1..e3bb969ce6 100644
--- a/plugins/ruflo-adr/scripts/lib/index-records.mjs
+++ b/plugins/ruflo-adr/scripts/lib/index-records.mjs
@@ -11,6 +11,19 @@ export function adrRecordKey(adr) {
return `${adr.id}::${basename(adr.file, '.md')}`;
}
+// #4126: ids of indexed ADRs whose status the parser could not classify (status: Unknown).
+// adr-verify reports these so a skipped ADR cannot hide behind a "healthy" graph.
+export function unknownStatusIds(entries) {
+ const ids = [];
+ for (const entry of entries) {
+ const value = typeof entry?.value === 'string' ? entry.value : '';
+ if (!/^status:\s*unknown\s*$/im.test(value)) continue;
+ const id = String(entry.key || '').split('::')[0];
+ if (id) ids.push(id);
+ }
+ return ids;
+}
+
export function adrRecordValue(adr) {
return `${adr.title} β€” ${adr.context || '(no context)'}\n\n` +
`file: ${adr.file}\n` +
diff --git a/plugins/ruflo-adr/scripts/lib/parse-adrs.mjs b/plugins/ruflo-adr/scripts/lib/parse-adrs.mjs
index 3078054896..58e964fce1 100644
--- a/plugins/ruflo-adr/scripts/lib/parse-adrs.mjs
+++ b/plugins/ruflo-adr/scripts/lib/parse-adrs.mjs
@@ -36,6 +36,9 @@ export function normalizeAdrId(raw) {
return digits.length >= 4 ? `ADR-${digits}` : `ADR-${digits.padStart(3, '0')}`;
}
+// #4126: an index table (README.md, index.md) or a template (template*.md) in docs/adr is not an ADR.
+const NON_ADR_FILE = /^(?:readme|index|template[^/]*)\.md$/i;
+
export function findAdrs(dir, out = [], visited = new Set()) {
let canonical;
try { canonical = realpathSync(dir); } catch { return out; }
@@ -50,7 +53,7 @@ export function findAdrs(dir, out = [], visited = new Set()) {
try { st = statSync(p); } catch { continue; }
if (st.isDirectory()) {
findAdrs(p, out, visited);
- } else if (e.endsWith('.md') && (p.includes('/docs/adr/') || p.includes('/docs/adrs/'))) {
+ } else if (e.endsWith('.md') && !NON_ADR_FILE.test(e) && (p.includes('/docs/adr/') || p.includes('/docs/adrs/'))) {
out.push(p);
}
}
@@ -111,7 +114,12 @@ function parseStatus(text) {
if (m) return m[1].trim();
// Also handle full-bold MADR style: **Status: Value** (entire phrase bolded)
m = /^[-*+]?\s*\*\*Status:\s*([A-Za-z][A-Za-z\- ]*?)(?:\s*\([^)]*\))?\*\*\s*$/m.exec(text);
- return m ? m[1].trim() : 'Unknown';
+ if (m) return m[1].trim();
+ // #4126: real status lines carry more than one parenthetical: a link ("superseded by
+ // [ADR-025](...) (2026-07-02)"), a date plus a note ("accepted (2026-07-02) β€” spike
+ // closed"), an amendment marker. The leading keyword is the status; ignore the rest.
+ m = /^[-*+]?\s*\*\*Status:?\*\*:?[ \t]*\**[ \t]*([A-Za-z][A-Za-z-]*)\b/m.exec(text);
+ return m ? m[1] : 'Unknown';
}
function parseDate(text) {
@@ -189,6 +197,13 @@ function parseLinks(text, selfId) {
for (const value of values('(?:Amended[ -]by|Amends)')) for (const ref of extractAdrRefs(value)) out.push({ from: selfId, to: ref, relation: 'amends' });
for (const value of values('(?:Related|Relates)')) for (const ref of extractAdrRefs(value)) out.push({ from: selfId, to: ref, relation: 'related' });
for (const value of values('Depends[ -]on')) for (const ref of extractAdrRefs(value)) out.push({ from: selfId, to: ref, relation: 'depends-on' });
+ // #4126: "Status: superseded by ADR-025" names the superseding ADR; the edge runs
+ // old -> new, the same direction a "Supersedes:" line in the newer ADR produces.
+ const sb = /^[-*+]?\s*\*\*Status:?\*\*:?[ \t]*\**[ \t]*superseded[ \t]+by\b(.*)$/im.exec(text);
+ if (sb) {
+ const [ref] = extractAdrRefs(sb[1].replace(/\[([^\]]*)\]\([^)]*\)/g, '$1'));
+ if (ref && ref !== selfId) out.push({ from: selfId, to: ref, relation: 'supersedes' });
+ }
return out;
}
diff --git a/plugins/ruflo-adr/scripts/smoke.sh b/plugins/ruflo-adr/scripts/smoke.sh
index 05ab5f7615..9a5c409d04 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.5.7 with new keywords"
+step "1. plugin.json declares 0.5.8 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.5.7" ]]; then
- bad "expected 0.5.7, got '$v'"
+if [[ "$v" != "0.5.8" ]]; then
+ bad "expected 0.5.8, got '$v'"
else
miss=""
for k in lifecycle compliance causal-graph mcp; do
diff --git a/plugins/ruflo-adr/scripts/verify.mjs b/plugins/ruflo-adr/scripts/verify.mjs
index e832fffb0b..1c00d41898 100755
--- a/plugins/ruflo-adr/scripts/verify.mjs
+++ b/plugins/ruflo-adr/scripts/verify.mjs
@@ -12,7 +12,7 @@
// VERIFY_STRICT=1 node scripts/verify.mjs # exit 1 on ANY issue (default: only on cycles)
// ADR_ROOT=/path/to/repo node scripts/verify.mjs # same root import.mjs was run with
-import { CLI_PKG, parseEdgeKey } from './lib/index-records.mjs';
+import { CLI_PKG, parseEdgeKey, unknownStatusIds } from './lib/index-records.mjs';
import { spawnCliSync } from './lib/ruflo-cli.mjs';
// Import/reindex always use the default CLI's SQLite store (#2781). Reading
@@ -136,6 +136,10 @@ function findCycle(node, visited, stack) {
}
for (const n of supersedesGraph.keys()) findCycle(n, new Set(), new Set());
+// #4126: an ADR the importer could not classify is skipped by adr-review (it only enforces
+// accepted ADRs), so it must not hide behind a healthy-looking graph.
+const unknownStatus = [...new Set(unknownStatusIds(patternEntries))];
+
const result = {
adrCount: adrIds.size,
edgeCount: edges.length,
@@ -143,6 +147,7 @@ const result = {
danglingRefs,
danglingFroms,
cycles: [...new Set(cycles)],
+ unknownStatus,
};
if (process.env.VERIFY_FORMAT === 'json') {
@@ -160,10 +165,15 @@ if (process.env.VERIFY_FORMAT === 'json') {
console.log(`| Dangling 'to' refs | ${result.danglingRefs.length} |`);
console.log(`| Dangling 'from' refs | ${result.danglingFroms.length} |`);
console.log(`| Supersede cycles | ${result.cycles.length} |`);
+ console.log(`| ADRs with Unknown status | ${result.unknownStatus.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.unknownStatus.length) {
+ console.log('\n### Unknown status (adr-review skips these: fix the Status line)');
+ for (const id of result.unknownStatus.slice(0, 20)) console.log(`- ${id}`);
+ }
if (result.cycles.length) {
console.log('\n### Cycles (DATA CORRUPTION β€” fix immediately)');
for (const c of result.cycles) console.log(`- ${c}`);
@@ -171,6 +181,6 @@ if (process.env.VERIFY_FORMAT === 'json') {
}
const strict = process.env.VERIFY_STRICT === '1';
-if (result.cycles.length || (strict && (result.danglingRefs.length || result.danglingFroms.length))) {
+if (result.cycles.length || (strict && (result.danglingRefs.length || result.danglingFroms.length || result.unknownStatus.length))) {
process.exit(1);
}
diff --git a/plugins/ruflo-adr/skills/adr-verify/SKILL.md b/plugins/ruflo-adr/skills/adr-verify/SKILL.md
index 12fa2ed621..810ef3c4f1 100644
--- a/plugins/ruflo-adr/skills/adr-verify/SKILL.md
+++ b/plugins/ruflo-adr/skills/adr-verify/SKILL.md
@@ -1,6 +1,6 @@
---
name: adr-verify
-description: Read back adr-patterns + adr-edges namespaces, surface dangling refs / supersede cycles / status mismatches; exit 1 on cycles
+description: Read back adr-patterns + adr-edges namespaces, surface dangling refs / supersede cycles / Unknown statuses; exit 1 on cycles
argument-hint: ""
allowed-tools: Bash mcp__plugin_ruflo-core_ruflo__memory_list mcp__plugin_ruflo-core_ruflo__memory_retrieve
---
diff --git a/scripts/ci-test-excluded.txt b/scripts/ci-test-excluded.txt
index f7fa8e4d27..da3744a85e 100644
--- a/scripts/ci-test-excluded.txt
+++ b/scripts/ci-test-excluded.txt
@@ -97,3 +97,4 @@ plugins/ruflo-mods/tests/selfcheck.test.ts
plugins/ruflo-testgen/scripts/tdd-repair/tdd-repair.test.mjs
plugins/ruflo-core/scripts/command-recording-switch.test.cjs
tests/regression/oct12-coverage.test.cjs
+plugins/ruflo-adr/scripts/__tests__/adr-status-forms-4126.test.mjs