Knowledge-quality benchmark

Meridians treats its internal knowledge base as an operational system: it needs a map, boundaries, and evidence about what will be hard to maintain. The benchmark measures the shape of that system without pretending to grade whether the prose is true.

Run it

npm run knowledge-insights
npm run gen:knowledge-quality
npm run gen:quality-worklog

The first command writes a local, gitignored review bundle at knowledge-base/insights/knowledge/, using the same midnight/light theme and one-question-per-chart discipline as repo-insights. The second produces the committed quality report, its machine-readable JSON sibling, and a separate generated Mermaid topology. It also runs in npm run gen:all.

gen:quality-worklog turns the separate static-analysis, change-history, documentation-drift, and knowledge-shape reports into a generated maintenance queue. It does not assign a score: an item is promoted only when independent signals overlap, then still requires inspection against the underlying contract.

What it measures

• Tree shape: topical leaves, branch count, depth, local hubs, and documents left at knowledge-base/ root.
• Reader cost: leaf-size distribution, leaves over the 240-line review threshold, and inbound maintained navigation links.
• Technical maintenance: source-path anchors on the architecture, governance, operations, and conventions branches; use the staleness report to decide whether an anchored claim needs re-reading.
• Diagram boundaries: maintained Mermaid sources belong in knowledge-base/diagrams/; generated aggregates belong in knowledge-base/generated/diagrams/. Mermaid inside a knowledge leaf is surfaced as leakage.
• Trend: a committed baseline and 90/365-day knowledge-change counts from git history.

How to use the findings

Treat a finding as a prompt to read the branch, never as an automatic migration instruction. Split a leaf only when it contains multiple reader questions. Add a small README.md or index.md when a directory becomes a branch. Move a diagram into a single-purpose diagram leaf, then regenerate the aggregate. Keep the docs root as a router rather than a catch-all.

The report intentionally has no composite score. A single number would reward fragmentation and false links; the individual signals preserve the judgment needed to make the tree more legible.