Hyperresearch Linting Checks: A Complete Guide to Vault Validation Rules

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, 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, 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 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 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 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 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:

hyperresearch lint --json

Run a specific rule in isolation to debug scaffold compliance:

hyperresearch lint --rule scaffold-prompt --json

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

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, 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, 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}