voyage/lib/review/rule-catalogue.mjs

// lib/review/rule-catalogue.mjs
// Canonical rule catalogue for /trekreview.
//
// 18 rule keys, 4-tier severity (matches brief contract). Decision 98 added
// CLAUDE_MD_DEVIATION and CLAUDE_MD_STALE (both MINOR): a change that breaks, or
// makes untrue, a line of the target repo's tracked instruction files.
// llm-security 5-tier alignment is a v1.1 candidate.
//
// Ordre 5 (review_version 1.1) added the two engine keys: findings from Claude
// Code's own `/code-review` and `/security-review` enter the coordinator under
// them when no narrower key fits (wrap, not a new engine). A third engine key,
// CODE_REVIEW_IMPROVEMENT (MINOR), takes a /code-review finding whose category
// is an improvement rather than a defect (simplification, efficiency, reuse,
// style, readability): the second voyage-lekerepo trial (2026-10-08) saw a pure
// simplification proposal enter as MAJOR and drive the verdict.
//
// E 2.3 (decision 167) added SECURITY_RISK (BLOCKER): Voyage's own security
// key, for a security finding by its own reviewers (plan-critic,
// scope-guardian, the code reviewer's part for command texts) that
// SECURITY_INJECTION does not cover. SECURITY_REVIEW_VULNERABILITY is the
// engines' key only (`/security-review`, and Claude Security since E 3.1):
// Voyage's reviewers never use it, and a finding under it is never Voyage's
// own (lib/review/threat-model.mjs).
//
// `memory_route` decides where a finding class that recurs across two
// review.md files is proposed as project memory (P5, lib/review/recurrence.mjs):
//   'check' - mechanical: a deterministic check can catch it;
//   'rule'  - judgement: a line in the target repo's `.claude/rules/` file;
//   null    - never proposed: review hygiene (about the review itself, not the
//             target code), or a catch-all key (the three engine keys) whose
//             members share nothing but their source.
// Routing borrowed from Pocock `skills/in-progress/retro/SKILL.md:19` (MIT).

export const SEVERITY_VALUES = Object.freeze(['BLOCKER', 'MAJOR', 'MINOR', 'SUGGESTION']);

export const CATEGORY_VALUES = Object.freeze([
  'conformance',
  'correctness',
  'scope',
  'tests',
  'security',
  'maintenance',
]);

export const RULE_CATALOGUE = Object.freeze([
  Object.freeze({
    rule_key: 'MISSING_BRIEF_REF',
    severity: 'MAJOR',
    category: 'conformance',
    description: 'Finding lacks brief_ref pointing to the brief section it traces back to.',
    memory_route: null,
  }),
  Object.freeze({
    rule_key: 'UNIMPLEMENTED_CRITERION',
    severity: 'BLOCKER',
    category: 'conformance',
    description: 'A brief Success Criterion has no corresponding implementation in the delivered code.',
    memory_route: 'rule',
  }),
  Object.freeze({
    rule_key: 'SCOPE_CREEP_BUILT',
    severity: 'MAJOR',
    category: 'scope',
    description: 'Code implements features beyond what the brief requested.',
    memory_route: 'rule',
  }),
  Object.freeze({
    rule_key: 'NON_GOAL_VIOLATED',
    severity: 'BLOCKER',
    category: 'scope',
    description: 'Code implements something the brief explicitly listed as a Non-Goal.',
    memory_route: 'rule',
  }),
  Object.freeze({
    rule_key: 'MISSING_TEST',
    severity: 'MAJOR',
    category: 'tests',
    description: 'Delivered behavior has no automated test coverage.',
    memory_route: 'check',
  }),
  Object.freeze({
    rule_key: 'SECURITY_INJECTION',
    severity: 'BLOCKER',
    category: 'security',
    description: 'Code path constructs commands, queries, or templates from untrusted input without sanitization.',
    memory_route: 'rule',
  }),
  Object.freeze({
    rule_key: 'PLACEHOLDER_IN_CODE',
    severity: 'MAJOR',
    category: 'maintenance',
    description: 'Committed code contains TBD/TODO/FIXME/XXX/console.log/debugger placeholders.',
    memory_route: 'check',
  }),
  Object.freeze({
    rule_key: 'MISSING_ERROR_HANDLING',
    severity: 'MINOR',
    category: 'correctness',
    description: 'Code path can fail silently (uncaught promise, unchecked return, missing try/catch on I/O).',
    memory_route: 'rule',
  }),
  Object.freeze({
    rule_key: 'UNDECLARED_DEPENDENCY',
    severity: 'MAJOR',
    category: 'maintenance',
    description: 'Code imports or invokes something not declared in package.json / not bundled / not present in PATH.',
    memory_route: 'check',
  }),
  Object.freeze({
    rule_key: 'PLAN_EXECUTE_DRIFT',
    severity: 'MAJOR',
    category: 'conformance',
    description: 'Delivered code diverges from what the plan said would be built (different file, different approach, different API).',
    memory_route: 'rule',
  }),
  Object.freeze({
    rule_key: 'BROKEN_SUCCESS_CRITERION',
    severity: 'BLOCKER',
    category: 'conformance',
    description: 'A brief Success Criterion is implemented but the verification command/test fails or is structurally incorrect.',
    memory_route: 'check',
  }),
  Object.freeze({
    rule_key: 'COVERAGE_SILENT_SKIP',
    severity: 'MAJOR',
    category: 'tests',
    description: 'Triage gate skipped a file without recording it in the Coverage section of review.md (hidden truncation).',
    memory_route: null,
  }),
  Object.freeze({
    rule_key: 'CODE_REVIEW_DEFECT',
    severity: 'MAJOR',
    category: 'correctness',
    description: "A defect reported by Claude Code's /code-review that no narrower rule_key covers.",
    memory_route: null,
  }),
  Object.freeze({
    rule_key: 'CODE_REVIEW_IMPROVEMENT',
    severity: 'MINOR',
    category: 'maintenance',
    description: "An improvement (simplification, efficiency, reuse, style, readability) reported by Claude Code's /code-review, not a defect.",
    memory_route: null,
  }),
  Object.freeze({
    rule_key: 'SECURITY_REVIEW_VULNERABILITY',
    severity: 'BLOCKER',
    category: 'security',
    description: "A vulnerability reported by a security engine (Claude Security, or Claude Code's /security-review) that no narrower rule_key covers. The engines' key only: Voyage's own reviewers use SECURITY_RISK.",
    memory_route: null,
  }),
  Object.freeze({
    rule_key: 'SECURITY_RISK',
    severity: 'BLOCKER',
    category: 'security',
    description: "Voyage's own security finding (a concrete attack path, high confidence) that SECURITY_INJECTION does not cover.",
    memory_route: 'rule',
  }),
  // memory_route null: a lesson about the instruction files would feed back into them.
  Object.freeze({
    rule_key: 'CLAUDE_MD_DEVIATION',
    severity: 'MINOR',
    category: 'conformance',
    description: "A change that breaks a line of the target repo's tracked CLAUDE.md, AGENTS.md or .claude/rules file.",
    memory_route: null,
  }),
  Object.freeze({
    rule_key: 'CLAUDE_MD_STALE',
    severity: 'MINOR',
    category: 'conformance',
    description: 'A change that makes a line of such an instruction file untrue.',
    memory_route: null,
  }),
]);

export const MEMORY_ROUTES = Object.freeze(['check', 'rule']);

export const RULE_KEYS = Object.freeze(new Set(RULE_CATALOGUE.map((r) => r.rule_key)));

/**
 * Look up a rule entry by its key.
 * @param {string} key
 * @returns {object|null} the frozen entry, or null if not found
 */
export function getRule(key) {
  if (typeof key !== 'string') return null;
  for (const entry of RULE_CATALOGUE) {
    if (entry.rule_key === key) return entry;
  }
  return null;
}