mdx knowledge loop

an agentic refactoring applied a code standard to 900+ files over concurrent agent runs. rules lived in a guru corpus; a project AGENTS.md documented local application. three failures:

• humans could not find which rule covered a specific file type.
• agents scraped prose for decision criteria and misread parenthetical exceptions as general rules.
• the ledger of converted files drifted from the source documents when a rule changed mid-run — agents before the change applied the old rule, agents after the new one, with no way to know which agent ran under which version. audit gap: was a file skipped by exception or by agent failure?

prose fails both audiences: humans cannot navigate it; agents must guess decision criteria from narrative. the invariant is one authored source whose meaning is queryable without being rewritten by its queries. a derived structured index gives agents exact rows instead of scraped parentheticals; a separate mutable ledger keeps "what the rule says" and "what has been applied" from impersonating each other.

• procedure: frontmatter-rich MDX; agents receive an exact intake prompt pointing to it.
• indexer: finds the nearest Git root, rebuilds a SQLite database under .agents/db, parses Markdown/MDX into documents, frontmatter rows, headings, components, links, blocks, and an FTS5 index.
• ledger: mutable work state, separate from the derived index — the index answers what standards say; the ledger records runs, findings, slices, and verification evidence.

source MDX explains an approved rule; the ledger records whether a repository applied and verified it. neither can impersonate the other.

when instructions must serve people and agents, author the explanation as MDX and derive a queryable index from it. separate immutable knowledge from mutable execution state. never let a generated index become the authority for either meaning or completion.

rebuild from a known document set, then query a frontmatter field, an FTS term, a path glob, and a parsed component. modify a source file and rebuild to prove the index follows source rather than becoming a writable cache. verify ledger state independently so a document query cannot be mistaken for evidence that implementation is complete.

bad

Refactoring guide (prose form)

Use named imports for libraries. There are some exceptions for internal packages,
see line 47 below.

Common case:

import { foo, bar } from "lib";

Exceptions:

In some cases (e.g. when the package is owned code), use namespace imports.
The drizzle ORM is special, see the table below.

the agent must infer: which files count as "internal"? which "cases" use namespace imports? is "owned code" the same as "internal package"? a concurrent run starts before the guide gains a new exception; one agent follows the old rule, another the new. afterwards no record shows which agent saw which version.

good

---
kind: decision
status: active
appliedSince: 2026-01-15
domain: import-composition
---

# named imports for libraries

...

<DataTable>
  <Row>
    <Cell>use-case</Cell>
    <Cell>pattern</Cell>
    <Cell>applies-to</Cell>
  </Row>
  <Row>
    <Cell>external library</Cell>
    <Cell>named imports</Cell>
    <Cell>drizzle-orm, zod, ...</Cell>
  </Row>
  <Row>
    <Cell>owned workspace package</Cell>
    <Cell>namespace import</Cell>
    <Cell>@scope/base</Cell>
  </Row>
</DataTable>

the agent queries "show me rules where applies-to matches 'drizzle-orm'" and gets the exact row. appliedSince tells an agent which version it reads when the guide changes. the ledger records which run saw which version, separating "agent skipped this file" from "agent ran before the rule was clarified."

mdx as interface · mdxquery · slices