Reading comments

A Warden comment is a small receipt: actionability tier, review category, confidence, file range, claim, suggested action, and the verified sources that earned the interruption.

Tiers

Tier 1Block

Blocking issue. Fix before merging.

Tier 2Fix

Real issue or risk. Usually worth fixing in the current change.

Tier 3Consider

Style, cleanup, or lower-confidence concern. Hidden unless verbose output asks for it.

Categories

correctness security vulnerability contract scalability consistency deadcode committability clarity style leverage deduplication tests

Categories define reading order, not severity. A Tier 2 correctness finding can appear before a Tier 1 style concern because the review is optimized for what developers should understand first. leverage sits before deduplication because a library or stdlib replacement can remove repeated code entirely.

Sources

toolStructured output from TSC, ESLint, jscpd, npm audit, or deterministic runners.

repositoryA file path, line, and snippet from the reviewed repo. The verifier checks a small line window for a substring match.

advisoryOSV-backed vulnerability records. Advisories without an OSV record are dropped.

api_defPackage type definition lookups for library API claims, cached by package, version, and symbol.

Citation discipline

A claim without acceptable grounding should be dropped rather than dressed up as certainty.

Degraded workers

Metadata shapeCommentSet

{
  "degradedWorkers": [
    {
      "kind": "actionable",
      "topic": "noise-filter",
      "message": "Skipped generated subtree before runner dispatch."
    }
  ]
}

Actionable entries appear in the normal CLI output. Warnings and info remain available in JSON or verbose mode.

Why this exists

Partial failure is safer when it is visible. Warden should say what did not run instead of silently narrowing the review.