Decision Guardian – Auto-surface architectural context on PRs and CLI

Hey HN, I’m Ali.

I built Decision Guardian to solve a problem I call "institutional amnesia." Senior engineers build complex systems (like highly-tuned DB connection pools or sensitive auth middleware) and document the "why" in wikis or ADRs. But inevitably, a new developer modifies that code without reading the docs, and things break. While tools like CODEOWNERS are great for telling you who needs to review a file, I needed something that automatically tells the developer why the review matters before they even ask.

What it is: Decision Guardian is an open-source tool that shifts teams from passive documentation to active enforcement. You write your architectural decisions in a standard Markdown file (e.g., .decispher/decisions.md) and map them to file paths using glob patterns or advanced JSON rules. When a developer modifies those protected files, it automatically analyzes the diff and drops a structured comment into the Pull Request explaining the context, warnings, and checklists.

I just released v1.1, which includes a major internal SOLID refactor. The core engine is now 100% decoupled from GitHub (using ISCMProvider and ILogger interfaces), allowing it to ship as a standalone 430KB CLI (npx decision-guardian check) that works locally, in pre-commit hooks, or on GitLab/Jenkins.

Under the hood (How it works): I wanted this to be fast and secure enough to run on massive enterprise repositories, which required a few fun technical implementations:

O(1) Pattern Matching: Naively matching N decisions against M files in a 3,000+ file PR is painfully slow. The core engine compiles all file patterns into a Prefix Trie (an Aho-Corasick variant), turning candidate lookup into an O(1) operation relative to the number of decisions.

ReDoS-Protected VM Sandbox: For complex rules, you can use Regex to scan diff contents (e.g., detecting hardcoded credentials). Because user-supplied regex can cause catastrophic backtracking, all regex evaluation runs inside an isolated Node VM sandbox with a hard 5-second timeout and pre-flight safe-regex checks.

Progressive Comment Truncation: GitHub limits PR comments to 65,536 characters. To prevent failures on massive PRs, the tool uses a 6-layer progressive truncation algorithm that intelligently summarizes details before falling back to a hard truncation.

Privacy & Telemetry: I know HN cares deeply about telemetry. v1.1 introduces anonymous usage metrics to help me understand performance (e.g., node version, duration, match counts). However, I designed it with strict privacy constraints:

Zero PII: It never collects source code, file contents, repo names, branches, or paths.

Runtime Blocklist: The privacy module physically validates every payload against a blocklist before sending. If any blocked field is detected, it throws an error and rejects the payload.

Open Source Backend: It is fire-and-forget (never slows down the tool), entirely opt-out (DG_TELEMETRY=0), and the Cloudflare Worker backend code is fully open-source in the repo.

Links:

Repo: https://github.com/DecispherHQ/decision-guardian

Docs/Architecture: https://decision-guardian.decispher.com

I also included 5 production-ready templates (security, database, api, etc.) to help teams get started instantly.

I’d love to hear your thoughts on the architecture, the Trie implementation, or how your teams currently handle enforcing ADRs during code reviews!