Kodus-rules

Machine-readable code-review policy consumed by Hermes when reviewing repositories and pull requests. The repository name reflects the Kodus-style review model and configuration, but Hermes is the review engine that loads and interprets these rules.

The goal is high-signal review: prioritize demonstrable security, correctness, reliability and performance defects; avoid speculative findings and avoid turning stylistic or project-specific preferences into blocking issues.

Repository layout

• .kody-rules/review/*.yml — atomic review rules validated against schema/kody-rule.schema.json.
• schema/ — schemas for rules and MANIFEST.json.
• MANIFEST.json — ruleset/schema version and rule count.
• docs/HERMES_REVIEW_CONTRACT.md — mandatory interpretation and anti-false-positive contract for Hermes.
• docs/SEVERITY.md — severity and review-verdict semantics.
• docs/FINDING_FORMAT.md — canonical finding format.
• docs/CONTEXT_CONTRACT.md — precedence of repository/project context over the base ruleset.
• docs/VERSIONING.md — pinning, compatibility and failure behaviour.
• scripts/ and test/ — schema/invariant validation and manifest checks.
• default-kodus-config.yml — upstream/reference Kodus configuration; it is context/reference material, not the identity of the review engine.

Hermes review principles

1. Review changed code first and use surrounding repository context only to prove or disprove a finding.
2. Emit a finding only when a concrete code path and impact can be demonstrated from available evidence.
3. Do not infer missing architecture, authorization, deployment or runtime behaviour when the repository does not provide evidence for it.
4. Deduplicate findings that describe the same root cause; prefer the most specific applicable rule.
5. Security/correctness/reliability rules may block when evidence and severity justify it. Architecture, maintainability and style preferences are non-blocking unless repository context explicitly promotes them.
6. Project-specific instructions override generic architecture/style preferences but cannot downgrade a demonstrated critical security defect without an explicit, documented exception.

See docs/HERMES_REVIEW_CONTRACT.md for the complete contract.

Consuming this rule set

1. Pin a specific commit SHA or annotated tag; never consume a floating branch for a reproducible review.
2. Verify MANIFEST.json, its schemaVersion, and ruleCount.
3. Validate every rule against schema/kody-rule.schema.json.
4. Apply docs/HERMES_REVIEW_CONTRACT.md before emitting findings.
5. Apply project context according to docs/CONTEXT_CONTRACT.md.
6. Render accepted findings according to docs/FINDING_FORMAT.md and severity semantics.

For security-sensitive reviews, invalid or unavailable policy must fail closed as described in docs/VERSIONING.md.

Contributing

See CONTRIBUTING.md. Local validation:

npm install
npm run validate-rules
npm run check-manifest
npm test