# Hyperresearch Linting Checks: A Complete Guide to Vault Validation Rules

> Discover Hyperresearch linting checks for validating research vaults. Learn how to ensure structural metadata, provenance, integrity, and compliance with 25+ checks.

- Repository: [Jordan Gibbs/hyperresearch](https://github.com/jordan-gibbs/hyperresearch)
- Tags: how-to-guide
- Published: 2026-09-13

---

**Hyperresearch performs 25+ linting checks via the `hyperresearch lint` command to validate structural metadata, provenance chains, content integrity, and workflow compliance in research vaults.**

The `jordan-gibbs/hyperresearch` repository ships with a built-in health-check system that enforces academic rigor on markdown-based knowledge bases. According to the source code in **[`src/hyperresearch/cli/lint.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/lint.py)**, a centralized **`RULES`** dictionary defines every validation check, assigning severities of *warning*, *error*, or *info* to ensure vaults maintain integrity across complex research pipelines.

## Core Linting Architecture

The linting engine resides in **[`src/hyperresearch/cli/lint.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/lint.py)**, where the `RULES` dictionary maps rule names to validation functions. Each rule inspects a specific aspect of the vault structure and returns standardized issue objects containing the rule name, severity level, affected note identifier, file path, and human-readable message. The command aggregates all applicable rules by default, or isolates a single rule when invoked with the `--rule` flag.

The test suite in **[`tests/test_cli/test_lint.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/tests/test_cli/test_lint.py)** documents expected behavior for each validation, demonstrating how the CLI processes vaults and returns JSON payloads containing an `issues` array.

## Metadata and Structure Validation

Hyperresearch enforces strict metadata hygiene through rules that check for completeness and consistency across the vault.

The **`missing-title`** rule ensures every note contains a non-empty title, while **`missing-tags`** and **`missing-summary`** require non-index notes to carry classification tags and summary fields. The **`uncurated`** rule specifically targets draft notes, verifying they include `tier` and `content_type` metadata for proper categorization.

Additional structural checks include:
- **`duplicate-ids`** – Errors when multiple notes share identical identifiers
- **`empty-notes`** – Flags notes with no body content
- **`orphaned-notes`** – Detects notes lacking inbound or outbound wiki-links
- **`broken-links`** – Identifies wiki-links that fail to resolve to existing notes

## Workflow and Provenance Verification

The linting system validates research pipeline completeness through workflow-specific rules. The **`workflow`** rule verifies the existence of required Hyperresearch artifacts including scaffold notes, loci files, and interim reports. The **`scaffold-prompt`** rule enforces the "gospel" requirement that scaffold notes must begin with a verbatim user prompt blockquote.

Provenance integrity is guarded by several specialized checks:
- **`provenance`** – Validates breadcrumb chains (`*Suggested by [[…]]`) form a rooted tree with at least one seed note, ensuring no dangling links exist and the guided reading loop fired
- **`locus-coverage`** – Guarantees every entry in [`research/loci.json`](https://github.com/jordan-gibbs/hyperresearch/blob/main/research/loci.json) has a corresponding interim report note while flagging duplicates
- **`audit-gate`** – Blocks synthesis when the latest conformance audit contains unresolved *CRITICAL* findings, surfacing *IMPORTANT* findings as advisory warnings

## Content Integrity and Quality Gates

Hyperresearch employs semantic linting to detect hallucinations and citation errors in final reports. The **`quote-integrity`** rule scans quoted spans in deliverables and errors when text cannot be found verbatim in any vault note. The **`numeric-consistency`** check flags numbers appearing in reports that lack traceability to a specific claim or cited note.

Citation-specific validations include:
- **`retracted-citations`** – Errors when reports cite sources marked as retracted without acknowledging the retraction
- **`citation-style-preservation`** – Ensures final reports maintain the citation style declared in the prompt (wikilinks or numbered references)
- **`instruction-coverage`** – Confirms every atomic entity, format requirement, and citation style declared in [`prompt-decomposition.json`](https://github.com/jordan-gibbs/hyperresearch/blob/main/prompt-decomposition.json) appears in the final output

## Maintenance and Coverage Checks

The linter monitors vault hygiene through maintenance rules. **`orphaned-raw-files`** detects disk leaks where files under `research/raw/` lack corresponding notes, while **`singleton-tags`** warns about tags appearing on only one note (likely typos). Temporal checks include **`expired-notes`** for content past expiry dates and **`stale-reviews`** for notes unreviewed in over 90 days.

Coverage validation rules ensure research completeness:
- **`extract-coverage`** – For single-pass runs, verifies at least 30% of source notes have associated extract notes
- **`patch-surgery`** – Validates that [`research/patch-log.json`](https://github.com/jordan-gibbs/hyperresearch/blob/main/research/patch-log.json) records all critical findings without skips
- **`wrapper-report`** – Ensures final reports contain all required terminal sections and do not leak scaffold-only content when wrapper contracts are present

## Running Hyperresearch Linting Checks

Execute the complete validation suite and receive machine-readable output:

```bash
hyperresearch lint --json

```

Run a specific rule in isolation to debug scaffold compliance:

```bash
hyperresearch lint --rule scaffold-prompt --json

```

Validate against a custom audit file for sub-run gating:

```bash
hyperresearch lint --audit-file research/audit_findings-run-a.json --json

```

Each command returns a JSON object containing an `issues` array with detailed severity classifications and remediation guidance.

## Summary

- **Hyperresearch linting checks** are defined in the `RULES` dictionary within [`src/hyperresearch/cli/lint.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/lint.py), covering over 25 validation rules
- The system validates **metadata completeness** (titles, tags, summaries), **provenance chains** (suggestion breadcrumbs, loci coverage), and **content integrity** (quote verification, numeric traceability)
- **Workflow rules** enforce pipeline structure requiring scaffold notes, interim reports, and proper audit gate compliance
- The CLI supports **granular execution** via `--rule` flags and **custom audit contexts** through `--audit-file` parameters
- All checks return standardized JSON payloads with severity levels of *warning*, *error*, or *info*

## Frequently Asked Questions

### How do I run Hyperresearch linting checks against a specific rule?

Use the `--rule` flag followed by the rule identifier to isolate validation. For example, `hyperresearch lint --rule provenance --json` executes only the provenance graph validation, returning JSON-formatted issues specific to breadcrumb chain integrity.

### What severity levels do Hyperresearch linting checks return?

The linting framework assigns three severity classifications: **error** for blocking issues that violate core invariants, **warning** for structural concerns that may affect workflow quality, and **info** for advisory notices. The `audit-gate` rule specifically distinguishes between *CRITICAL* findings (blocking) and *IMPORTANT* findings (advisory).

### Where are the linting rules defined in the Hyperresearch source code?

All validation logic resides in **[`src/hyperresearch/cli/lint.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/src/hyperresearch/cli/lint.py)**, where the `RULES` dictionary maps string identifiers like `quote-integrity` and `missing-title` to their respective validation functions. The accompanying test file **[`tests/test_cli/test_lint.py`](https://github.com/jordan-gibbs/hyperresearch/blob/main/tests/test_cli/test_lint.py)** demonstrates expected behavior for each rule and documents the CLI invocation patterns.

### Can Hyperresearch linting detect hallucinated content in research reports?

Yes. The **`quote-integrity`** rule specifically scans quoted spans in final reports and errors when the exact text cannot be located verbatim in any vault note. Additionally, **`numeric-consistency`** flags numerical claims lacking traceability to cited sources, preventing unsupported data from appearing in deliverables.