RigorLens

Deep audits. Cited evidence. Zero edits.

A deterministic, evidence-first orchestrator for exhaustive static software audits.
It understands the project before judging it, gives the model no editing tools, and writes one cited Markdown report.

Why RigorLens · How it works · Audit surface · Safety contract · CLI · Installation

Important

RigorLens is pre-release software. There is no public signed release yet. The source, controller, installers, native integrations, and release pipeline are present, but compatibility is declared only after the authenticated host gates pass. Do not install from an unverified archive or pipe network output into a shell.

Why RigorLens

Most AI review flows begin producing findings before they have proved that they understand the system. RigorLens reverses that order.

It creates a byte-attested mirror outside the target, discovers the stack and trust boundaries, builds a cited ProjectModel, routes the relevant engineering references through RuleDive, runs pinned static analyzers, and only then asks the selected engine to audit. A deterministic controller owns the entire run and is the only component allowed to publish the final report.

Understand first A project model covering modules, entrypoints, data flows, storage, deployment, tests, and trust boundaries must be established before any finding is accepted.

Evidence, not intuition High and critical findings require verifiable path:line evidence. Citations are checked again before publication and invented locations fail the run.

One report, zero edits RigorLens never patches the audited project. The only permitted persistent change is one new report below audit-reports/.

How It Works

flowchart LR
    T[Target project] --> B[Integrity baseline]
    B --> M[External immutable mirror]
    M --> P[Attested ProjectModel]
    M --> S[Static analyzers]
    D[Context7 documentation] --> A[Isolated audit passes]
    R[RuleDive references] --> A
    P --> A
    S --> A
    A --> L[Review loop: max 5]
    L --> V[Evidence and integrity validation]
    V --> O[One Markdown report]

Loading

1. Preflight verifies the engine, managed tools, versions, corpus, paths, Git state, and initial hashes.
2. Mirror materializes an external, symlink-free snapshot; analysis never runs against the live target.
3. Discover maps languages, frameworks, monorepos, entrypoints, dependencies, storage, CI, IaC, and deployment.
4. Model requires a cited logical model of the whole project before findings can exist.
5. Graph synchronizes CodeGraph in the mirror. Unsupported or empty graphs fall back to bounded ripgrep evidence with degraded coverage declared.
6. Ground resolves current engine and dependency documentation through Context7 without sending private source or secrets.
7. Scan runs only pinned static analyzers. Project builds, tests, hooks, migrations, and package scripts are never executed.
8. Audit routes compact rules first, then loads each relevant canonical reference in an isolated pass.
9. Review performs at most five passes and requires two consecutive passes without material change to converge.
10. Publish revalidates evidence, secrets, hashes, and paths, then atomically creates the sole authorized report.

Audit Surface

Every run evaluates the complete surface. A domain that is genuinely absent is marked N/A with evidence instead of being silently skipped.

System design	Delivery and operations	Assurance
Architecture	CI and release flow	Security
Code quality	Infrastructure as code	Secrets
Data and storage	Configuration	Supply chain
Concurrency	Reliability	Licenses
Performance	Tests, statically assessed	Documentation

The scanners

Tool	Pinned version	Role
CodeGraph	1.4.1	Symbols, callers, dependencies, and architectural paths inside the mirror
Context7	0.5.4	Current public documentation for the selected engine and detected dependencies
Trivy	0.72.0	Vulnerabilities, misconfiguration, licenses, and supply-chain signals
Gitleaks	8.30.1	Static secret discovery with redacted handling
ripgrep	15.1.0	Bounded textual fallback and targeted evidence collection

The Report

RigorLens creates exactly one file:

audit-reports/
  rigorlens-<timestamp>-<run-id>.md

The report is designed to be reviewable without hidden model state. It contains:

• verdict and selected failure threshold;
• cited logical project model and detected stack;
• coverage, degraded areas, and N/A evidence;
• findings ordered by severity and confidence;
• verified path:line evidence, impact, and prose-only recommendations;
• references and static tools used;
• limitations and unresolved uncertainty;
• review-loop history and convergence state;
• final integrity attestation.

No report may contain a patch, diff, implementation code block, exposed secret, absolute private path, or unsupported high/critical finding.

Safety Contract

Boundary	Enforced behavior
Model capabilities	No filesystem, shell, web, MCP, patch, or editing tools are granted to the internal engine process.
Target project	Existing files must retain their original hashes. Only one new report is permitted.
Execution	No project build, test, hook, package manager, migration, or generated-code command is run.
Analysis workspace	CodeGraph and all analyzers operate on an external controlled mirror.
Project instructions	AGENTS.md, CLAUDE.md, and similar files are read as untrusted context and cannot override audit safety.
Documentation lookup	Context7 receives public package names, versions, and generic questions, never internal code or secrets.
Findings	Critical and high severity claims require citations that resolve to collected evidence.
Publication	The deterministic controller validates content and atomically creates the report.

RuleDive

RuleDive is the internal documentation engine. It turns the bundled agent-rules-books corpus into a controlled, traceable audit input rather than one oversized prompt.

Task and detected stack
        |
        v
Compact mini-rule routing
        |
        v
Relevant canonical full rules
        |
        v
One isolated pass per reference
        |
        v
Compatibility reconciliation

The reference corpus contains 201 attested entries. Its 187 regular upstream files are byte-identical to commit 9c8763613514e4047d75c089533e09bc4b493c28; 14 upstream workbench full.md symlinks are represented as empty, regular, symlink-free sentinels for portable distribution. RuleDive uses the non-empty <slug>/<slug>.md documents as canonical full sources.

Files below references/agent-rules-books/ are immutable. Updates require a separately reviewed import and a regenerated SHA-256 manifest.

CLI

rigorlens audit [path] --engine auto|codex|claude --language auto|fr|en --fail-on critical|high|medium|low|none
rigorlens doctor
rigorlens references verify
rigorlens update
rigorlens uninstall
rigorlens version

auto selects the only available engine. If Codex and Claude Code are both present, an interactive terminal asks which one to use; non-interactive runs must select an engine explicitly.

--output is supported only when it resolves exactly to <path>/audit-reports. RigorLens does not permit an arbitrary output directory.

Exit codes

Code	Meaning
0	Complete audit below the selected threshold
1	Finding threshold reached
2	Audit incomplete
3	Integrity violation
4	Required engine, tool, network service, or prerequisite unavailable
5	Review loop did not converge within five passes

Native Integrations

Host surface	Entry point	Current status
Codex CLI engine	rigorlens audit --engine codex	Deterministic internal adapter supported
Codex skill	$rigorlens-audit	Conditional: the outer host cannot yet prove built-in tool invisibility
Claude Code command	/rigorlens:audit	Pending authenticated real-host CI validation

Each native integration is bound to one managed installation, engine, target, and randomly named MCP server. Custom installation prefixes are carried by the binding; plugin processes do not require users to export RIGORLENS_HOME.

Note

Codex and Claude Code are independent engines. RigorLens does not manufacture a consensus between them and does not claim compatibility from an unauthenticated smoke test.

Installation

Requirements

• Node.js 22.12 or newer for the installation bootstrap;
• an installed and authenticated Codex or Claude Code host;
• GitHub CLI (gh) for verified installation and updates;
• network access to Context7 and scanner vulnerability databases.

The installer provisions the pinned managed runtime and static tools, detects the operating system and available engines, previews every operation, displays the RIGORLENS wordmark, and asks for confirmation. NO_COLOR is honored. Reviewed automation can pass --yes on POSIX or -Yes on Windows.

Warning

No public release exists yet, so the commands below are a verified-release blueprint, not an immediately usable installer command. They become valid only after a signed release passes every release gate.

POSIX verified installation

POSIX:

set -eu
tag="$(gh release view --repo ostend972/rigorlens --json tagName --jq .tagName)"
work="$(mktemp -d)"
trap 'rm -rf -- "$work"' EXIT HUP INT TERM
gh release verify "$tag" --repo ostend972/rigorlens
gh release download "$tag" --repo ostend972/rigorlens --pattern install.sh --dir "$work"
gh release verify-asset "$tag" "$work/install.sh" --repo ostend972/rigorlens
gh attestation verify "$work/install.sh" --repo ostend972/rigorlens --signer-workflow ostend972/rigorlens/.github/workflows/release.yml
sh "$work/install.sh"

Windows PowerShell verified installation

Windows PowerShell:

$ErrorActionPreference = 'Stop'
function Invoke-VerifiedGh {
    & gh @args
    if ($LASTEXITCODE -ne 0) { throw "GitHub verification failed with exit code $LASTEXITCODE" }
}
$tag = Invoke-VerifiedGh release view --repo ostend972/rigorlens --json tagName --jq .tagName
$work = Join-Path ([System.IO.Path]::GetTempPath()) ("rigorlens-" + [guid]::NewGuid())
New-Item -ItemType Directory -Path $work | Out-Null
Invoke-VerifiedGh release verify $tag --repo ostend972/rigorlens
Invoke-VerifiedGh release download $tag --repo ostend972/rigorlens --pattern install.ps1 --dir $work
Invoke-VerifiedGh release verify-asset $tag (Join-Path $work "install.ps1") --repo ostend972/rigorlens
Invoke-VerifiedGh attestation verify (Join-Path $work "install.ps1") --repo ostend972/rigorlens --signer-workflow ostend972/rigorlens/.github/workflows/release.yml
& (Join-Path $work "install.ps1")

Development

npm ci
npm run references:verify
npm run typecheck
npm test
npm run build

Repository map

Path	Purpose
src/orchestrator/	Deterministic pipeline, evidence collection, review loop, and report rendering
src/engines/	Isolated Codex and Claude Code adapters
src/scanners/	Pinned static analyzer and Context7 integrations
src/reference/	RuleDive catalog, routing, and compatibility logic
src/platform/	Snapshot, confinement, integrity, path, and publication boundaries
integrations/native/	Native MCP bootstrap and host bindings
references/	Byte-attested immutable engineering corpus
scripts/install/	Interactive transactional installer
scripts/release/	Packaging, SBOM, provenance, attestation, and release gates
tests/	Unit, integration, adversarial, installer, native, and release-gate coverage

The release matrix covers Windows, macOS, and Linux, plus pinned Ruby, Python/TypeScript, Java, Go, Rust, and .NET fixtures. A release remains blocked until real installation, audit, upgrade, rollback, and uninstall paths pass for the declared host engines.

License and Attribution

RigorLens is released under the MIT License.

The bundled reference corpus retains its original MIT license and attribution. See NOTICE and THIRD_PARTY_NOTICES for the complete provenance and dependency notices.

Read the system. Prove the evidence. Leave the code untouched.