The Human-in-the-Loop Database: Inside marceloceccon/mdruleforge

AI agents are excellent at extracting business logic from legacy code, and terrible at getting it completely right. Here is how a hybrid Markdown-and-SQLite architecture forces human consensus before AI guesses become organizational truth.

6 min read • View on GitHub • More from marceloceccon

A robotic arm drops a gear onto a conveyor belt where human workers inspect it with calipers and magnifying glasses before stamping it for approval. This represents the AI generating logic that humans must manually verify. — Generative AI is the assembly line; human consensus is the quality control.

Key Takeaways

MDRuleForge acts as a hallucination firewall, ensuring AI-extracted business rules require human consensus before becoming organizational truth.
The system employs a hybrid storage architecture, using version-controllable Markdown for text content and SQLite for relational voting data.
A zero-dependency deployment model prioritizes pragmatism over cloud-native complexity, using local filesystems and synchronous database queries.

The Hallucination Firewall

Large Language Models blindly generate business rules from legacy code without understanding the operational context. While they are phenomenal at reading decades-old COBOL and extracting latent logic, they frequently hallucinate constraints that do not exist or miss edge cases that do.

If you pipe AI-extracted rules directly into production or official documentation, you are codifying errors. MDRuleForge is designed as a quarantine zone for AI output. It is a purpose-built "hallucination firewall" that treats AI-generated documentation not as truth, but as a highly suspicious draft.

The Hybrid Source-of-Truth

Relational databases are terrible for version-controlling long-form text. Conversely, Markdown files are terrible for querying relational consensus data, like who voted to approve a specific paragraph. MDRuleForge solves this by splitting the difference.

The core implementation relies on parsed YAML frontmatter and Markdown bodies. The system uses a section-based editing approach, splitting a single Markdown file into editable chunks via regex. These chunks are modified and seamlessly stitched back together, while better-sqlite3 handles the relational metadata.

The hybrid storage engine synchronizes file-system state with a relational database without a heavy ORM.

Forcing Consensus

An AI draft is useless until verified. The system implements a strict state machine to manage this workflow. When a user votes on a generated rule, the backend recalculates its status based on a configurable validation threshold.

A single "incorrect" vote instantly transitions a rule to a contested state. To prevent users from accidentally overwriting logic during conflict resolution, MDRuleForge utilizes a Longest Common Subsequence (LCS) algorithm to calculate divergence percentages on the fly, blocking reckless edits.

A heavy circular steel bank vault door with multiple distinct keyholes arranged in a circle. Several different human hands are simultaneously inserting and turning keys to unlock it. — Multi-user voting thresholds act like a multi-key vault, requiring consensus before a rule is validated.

The Pragmatist’s Stack

Modern web development often defaults to distributed microservices, introducing immense overhead. MDRuleForge actively rejects this trend, opting for a zero-dependency architecture that runs entirely within a single Docker container.

By combining a local filesystem, synchronous better-sqlite3, and reactive caching via file-watching, the application keeps the UI perfectly in sync with the disk. This approach eliminates network overhead and delivers a remarkably fast developer experience.

Feature	Traditional DB (Postgres)	Pure Markdown (Git)	MDRuleForge (Hybrid)
Version Control	Hard	Native	Native via Git
Relational Queries	Native	Impossible	Native via SQLite
Conflict Resolution	Locking	Git Merge	LCS Diffing & Voting
Infrastructure Footprint	Heavy	Zero	Minimal