Skip to content

FINDING_SPECIFICATION.md

Latest commit

 

History

History
95 lines (74 loc) · 3.61 KB

FINDING_SPECIFICATION.md

File metadata and controls

95 lines (74 loc) · 3.61 KB
Raw

HQE Finding & Artifact Specification

Protocol Version: HQE Protocol v5.0.0
Schema Definition: schemas/finding.schema.json

1. Finding Taxonomy

Every finding generated by HQE must have a unique, deterministic ID and adhere to standard taxonomic classifications:

HQE-<CATEGORY>-<INDEX>
Example: HQE-SEC-001, HQE-BUG-004, HQE-REL-012

1.1 Category Codes

Category Code Domain Focus Area
BOOT Initialization Startup crashes, environment configuration, dependency boot failures
SEC Security Vulnerabilities, authentication bypass, injections, secret exposure
BUG Correctness Logic errors, calculation bugs, off-by-one errors, state corruption
REL Reliability Race conditions, deadlocks, unhandled exceptions, resource leaks
PERF Performance Hot-path bottlenecks, memory bloat, excessive I/O, N+1 queries
UX User Experience CLI output formatting, error messaging clarity, input parsing
DX Dev Experience Build tooling friction, missing type annotations, test ergonomics
DOC Documentation Outdated READMEs, inaccurate API docs, missing examples
DEBT Technical Debt Dead code, severe architectural erosion, tight coupling
DEPS Dependencies Vulnerable packages, duplicate versions, deprecated libraries

2. Confidence & Verification Levels

To prevent hallucinations, findings must be tagged with explicit confidence markers:

confidence_levels:
  FACT:
    description: "Undeniable code-level proof. Static evidence unambiguously demonstrates the defect."
    status_mapping: ["CONFIRMED"]
  INFERENCE:
    description: "Strong logical deduction based on control/data flow across multiple files."
    status_mapping: ["OPEN", "CONFIRMED"]
  HYPOTHESIS:
    description: "Suspected issue requiring runtime validation, load testing, or external context."
    status_mapping: ["OPEN"]
  NEEDS_VERIFICATION:
    description: "Issue that cannot be confirmed without explicit validation steps."
    status_mapping: ["OPEN"]

3. Severity & Effort Matrix

Severity Tiers

  • CRITICAL: Immediate threat of exploitation, remote code execution, silent data loss, or total service failure.
  • HIGH: Severe logic defect, authentication flaw, memory leak in core loop, or critical data corruption.
  • MEDIUM: Moderate impact bug, non-critical vulnerability, intermittent race condition, or unhandled edge case.
  • LOW: Minor defect, cosmetic inconsistency, defense-in-depth gap, or minor performance degradation.
  • INFO: Architectural suggestion, documentation correction, or refactoring opportunity.

Effort Sizing

  • S (Small): 1–2 files, isolated fix, <1 hour implementation, trivial regression risk.
  • M (Medium): 2–5 files, requires test updates and boundary checking, moderate regression risk.
  • L (Large): Multi-module refactor, architectural change, backward-compatibility considerations, high regression risk.

4. Evidence Object Schema

Every finding MUST include concrete evidence objects. The evidence object must provide either a strict line range or an anchor with a grep signature:

{
  "path": "crates/hqe-core/src/auth.rs",
  "start_line": 142,
  "end_line": 148,
  "symbol": "verify_jwt_token",
  "snippet": "if token.is_empty() {\n    return Ok(Claims::default_admin());\n}"
}

Or using an anchor:

{
  "path": "crates/hqe-core/src/auth.rs",
  "anchor": "verify_jwt_token",
  "grep_signature": "if token.is_empty() \\{",
  "snippet": "if token.is_empty() {\n    return Ok(Claims::default_admin());\n}"
}