$ show av/facts
This is a Rust CLI tool called `facts` that implements a fact-driven development workflow. It manages a `.facts` file containing atomic, verifiable claims about a project, each with lifecycle tags (`@draft` → `@spec` → `@implemented`) and optional shell commands for automated verification. The tool provides a rich set of subcommands for listing, adding, editing, removing, linting, and checking facts, along with a terminal UI (TUI) built with Ratatui and Crossterm. It integrates with AI coding agents (Claude, Codex) to verify manual facts via an XML-based verdict protocol, and ships with bundled agent skills for discovery, refinement, and implementation. The project is self-hosting—it uses its own `.facts` file to describe itself—and is distributed via npm, PyPI, and direct install. The architecture is a monolith with clearly separated modules for parsing, writing, ID generation, tag filtering, file locking, and agent communication. The codebase demonstrates strong engineering practices: deterministic round-trip serialization, atomic file writes, advisory locking with stale detection, and a boolean expression evaluator for tag filters. It is actively maintained with a comprehensive test suite and CI/CD pipeline.
The LLM identified 4 files worth highlighting for reuse:
Implements advisory file locking via a `.facts.lock` file with stale lock detection (60-second timeout) and retry logic. The lock file contains the PID and timestamp, and the code checks if the owning process is still alive before breaking the lock. This is a reusable pattern for any CLI tool that needs to prevent concurrent writes to a shared file.
A boolean expression evaluator for tag filters supporting `and`, `or`, `not`, and parentheses. It parses a filter string into an AST and evaluates it against a set of tags. Also used for full-text search. This is a self-contained, generic component that could be extracted for any application needing flexible tag-based filtering.
Handles verification of manual facts by invoking an external AI agent (e.g., Claude, Codex). It builds prompts, sends batches of facts, parses XML verdicts (`<fact-verdict id="...">PASS/FAIL reason</fact-verdict>`), and handles timeouts and partial failures. Includes `sanitize_for_prompt()` to prevent prompt injection by escaping `<fact-verdict` tags, and `shell_escape()` for safe command-line argument passing. The protocol is reusable for any tool that needs agent-based validation.
Provides atomic file write using a temporary file and rename, with cleanup on failure. This is a standard but well-implemented pattern that ensures the `.facts` file is never left in a partially written state. The module is small, self-contained, and directly reusable in any Rust project that needs safe file updates.