adr-index

# ADR Index 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 with the on-disk ADR files - Bootstrapping ADR tracking on an existing codebase ## Steps 1. **Run the importer**: ```bash node plugins/ruflo-adr/scripts/import.mjs ``` 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. 3. **Verify graph integrity** (optional but recommended) via the sibling `adr-verify` skill, which runs `scripts/verify.mjs` and exits 1 on cycles. 4. **Search semantically** via `mcp__plugin_ruflo-core_ruflo__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, deterministic key `<relation>:<FROM>-><TO>`, value: ```json { "from": "ADR-097", "to": "ADR-086", "relation": "related", "capturedAt": "<ISO>" } ``` Both ADR records and relationship edges are stored with explicit upsert semantics. Re-running `adr-index` refreshes changed metadata in place and does not create duplicate copies of an unchanged semantic edge. ## 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`. ## What this skill cannot do `adr-index` only ever adds/upserts. If an ADR file was deleted (or a relation line removed from a surviving file), the row it wrote stays forever — `adr-verify` won't catch it either, since an orphan has no dangling ref and forms no cycle. Use the sibling `adr-reindex` skill to reconcile a deletion (issue #2666). ## 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 - `adr-reindex` (sibling skill) — drop-and-rebuild reconcile for a deleted ADR file (this skill can only add, never remove)