$ show hoangnb24/repository-harness
This repository implements a 'Repository Harness'—a Rust-based CLI framework designed to make software codebases legible and operable for AI agents. It functions as a control plane for agent-assisted development, managing project state (stories, decisions, traces) through a combination of Git-native documents and a durable SQLite layer. The system enforces architectural rules and invariants via mechanical validation rather than process bureaucracy, distinguishing between a generic 'Core' payload and product-specific 'Consumer' work (e.g., Symphony). Key capabilities include self-updating binaries, semantic changeset replay for auditability, and explicit agent skills for onboarding and auditing. Architecturally, the codebase follows a clean separation of concerns with a Rust workspace containing `harness` (core logic) and `harness-cli` (interface). It utilizes a repository pattern to decouple business logic from database access, implementing transactional logging via JSONL changesets that support idempotent replay. The tool manages its own lifecycle through a robust installer that supports cross-platform profiles (Core vs. Core+CLI) and handles file conflicts via deterministic three-way merges. Evidence capsules and epoch fencing ensure data integrity during agent interactions and state transitions. The project demonstrates a high level of engineering maturity through its focus on reproducibility and trust boundaries. It includes extensive documentation (ADRs, execution plans, stories) and a comprehensive test suite covering installer contracts, changeset rebuilds, and boundary checks. The separation of the 'Symphony' product into a distinct repository while retaining protocol primitives in the core highlights a mature approach to library vs. application boundaries.
The LLM identified 4 files worth highlighting for reuse:
Implements a deterministic three-way merge strategy for handling file conflicts during CLI updates. This component allows the harness to safely update managed files while preserving local changes where possible, using a base state, upstream state, and local state model. It is reusable for any tool that needs to manage file state across updates without destructive overwrites.
Manages atomic transitions between database states and changeset logs using file locking and journaling. This script ensures that state swaps (e.g., activating a new changeset) are crash-recoverable and prevents concurrent modification conflicts. It demonstrates a robust pattern for maintaining data integrity in distributed or multi-process environments.
Validates AI agent transcripts and evidence capsules using SHA-256 hashing and schema compliance checks. It verifies Git blobs, patches, and source ranges to ensure that agent actions are authenticated and reproducible. This component is reusable for any system requiring cryptographic verification of AI-generated artifacts.
Handles cross-platform repository integration by downloading prebuilt binaries, managing conflict resolution (merge/override), and injecting agent instruction blocks. It supports distinct installation profiles (Core vs. Core+CLI) to minimize payload size while maintaining compatibility. The script demonstrates a robust pattern for self-hosting tool installation with rollback protection.