Engineering-grade governance shell for deterministic document review

hermes-review-agent is not just a wrapper; it is a Governed Control Plane.

Its mission is to provide a deterministic, fail-closed orchestrator around the NousResearch/hermes-agent kernel. We separate the "Thinking" (Kernel) from the "Governing" (Shell) to ensure that every review result is grounded in explicit evidence, standard registries, and formal acceptance rules.

• Smart Owner, Dumb Tools: This repo owns the Planet/Policy, while adapters and kernels own the Execution.
• Fail-Closed by Design: If evidence is missing or the kernel degrades, the shell refuses to emit a formal report.
• DeepSeek Primary: Optimized for DeepSeek's specific reasoning patterns for high-recall issue detection.

The repository operates as a Governance Shell protecting the Upstream Kernel.

[ External Caller / Web UI ]
            |
            v
+-------------------------------------------------------+
| hermes-review-agent (Local Shell / Control Plane)     |
|                                                       |
|   - Task Governance & Basis Selection                 |
|   - Evidence Synthesis & Result Assembly              |
|   - Fail-Closed Safety Gates                          |
|                                                       |
|  +-------------------------------------------------+  |
|  | external/hermes-agent (Upstream Kernel)         |  |
|  |   - Judgment Engine & Reasoning                 |  |
|  +-------------------------------------------------+  |
|                                                       |
+-------------------------------------------------------+

All formal reviews follow this strict, audited execution chain:

graph LR
    A[TaskCompiler] --> B[ProfileResolver]
    B --> C[BasisPackResolver]
    C --> D[SupportPacketBuilder]
    D --> E[Hermes Main Review]
    E --> F[FinalReportAssembler]
    
    style F fill:#f96,stroke:#333,stroke-width:4px

1. TaskCompiler: Normalizes raw inputs into a strict ReviewBrief.
2. ProfileResolver: Determines the system classification and governance profile.
3. BasisPackResolver: Assembles laws, standards, and rule sets based on the profile.
4. SupportPacketBuilder: Prepares the visibility gaps and evidence pointers.
5. Hermes Main Review: Executes the judgment using the reasoning kernel.
6. FinalReportAssembler: The ONLY official exit point for synthesized reports.

make bootstrap

make dev

make eval-review

The Source of Truth for all governance and design resides in the docs/ hierarchy.

For a detailed layer-by-layer definition including frozen and legacy code paths, see docs/20-design/layer-governance.md.

This project follows the Harness Engineering governance model. All technical decisions and execution rules are codified in:

• [[AGENTS.md]]: The local execution contract for AI agents and human contributors.
• [[REPO_CATALOG.md]]: System-level repository mapping.

MIT © 2026 watsonctl

_{Publish the framework, govern the memory, trust the evidence.}