feat(ultraplan-local): add lib/review/rule-catalogue.mjs (12 rule keys)

plugins/ultraplan-local/lib/review/rule-catalogue.mjs

@@ -0,0 +1,106 @@
+// lib/review/rule-catalogue.mjs
+// Canonical rule catalogue for /ultrareview-local v1.0.
+//
+// 12 rule keys, 4-tier severity (matches brief contract).
+// llm-security 5-tier alignment is a v1.1 candidate.
+
+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.',
+  }),
+  Object.freeze({
+    rule_key: 'UNIMPLEMENTED_CRITERION',
+    severity: 'BLOCKER',
+    category: 'conformance',
+    description: 'A brief Success Criterion has no corresponding implementation in the delivered code.',
+  }),
+  Object.freeze({
+    rule_key: 'SCOPE_CREEP_BUILT',
+    severity: 'MAJOR',
+    category: 'scope',
+    description: 'Code implements features beyond what the brief requested.',
+  }),
+  Object.freeze({
+    rule_key: 'NON_GOAL_VIOLATED',
+    severity: 'BLOCKER',
+    category: 'scope',
+    description: 'Code implements something the brief explicitly listed as a Non-Goal.',
+  }),
+  Object.freeze({
+    rule_key: 'MISSING_TEST',
+    severity: 'MAJOR',
+    category: 'tests',
+    description: 'Delivered behavior has no automated test coverage.',
+  }),
+  Object.freeze({
+    rule_key: 'SECURITY_INJECTION',
+    severity: 'BLOCKER',
+    category: 'security',
+    description: 'Code path constructs commands, queries, or templates from untrusted input without sanitization.',
+  }),
+  Object.freeze({
+    rule_key: 'PLACEHOLDER_IN_CODE',
+    severity: 'MAJOR',
+    category: 'maintenance',
+    description: 'Committed code contains TBD/TODO/FIXME/XXX/console.log/debugger placeholders.',
+  }),
+  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).',
+  }),
+  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.',
+  }),
+  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).',
+  }),
+  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.',
+  }),
+  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).',
+  }),
+]);
+
+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;
+}

plugins/ultraplan-local/tests/lib/rule-catalogue.test.mjs

@@ -0,0 +1,54 @@
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import {
+  RULE_CATALOGUE,
+  RULE_KEYS,
+  SEVERITY_VALUES,
+  CATEGORY_VALUES,
+  getRule,
+} from '../../lib/review/rule-catalogue.mjs';
+
+test('RULE_CATALOGUE — every entry has all 4 required fields', () => {
+  for (const entry of RULE_CATALOGUE) {
+    assert.ok(typeof entry.rule_key === 'string' && entry.rule_key.length > 0, `bad rule_key: ${entry.rule_key}`);
+    assert.ok(typeof entry.severity === 'string' && entry.severity.length > 0, `bad severity: ${entry.severity}`);
+    assert.ok(typeof entry.category === 'string' && entry.category.length > 0, `bad category: ${entry.category}`);
+    assert.ok(typeof entry.description === 'string' && entry.description.length > 0, `bad description for ${entry.rule_key}`);
+  }
+});
+
+test('RULE_CATALOGUE — no duplicate rule_key', () => {
+  const seen = new Set();
+  for (const entry of RULE_CATALOGUE) {
+    assert.ok(!seen.has(entry.rule_key), `duplicate rule_key: ${entry.rule_key}`);
+    seen.add(entry.rule_key);
+  }
+  assert.equal(seen.size, RULE_CATALOGUE.length);
+});
+
+test('RULE_CATALOGUE — all severity values within enum', () => {
+  for (const entry of RULE_CATALOGUE) {
+    assert.ok(SEVERITY_VALUES.includes(entry.severity), `${entry.rule_key} has invalid severity: ${entry.severity}`);
+  }
+});
+
+test('RULE_CATALOGUE — all category values within enum', () => {
+  for (const entry of RULE_CATALOGUE) {
+    assert.ok(CATEGORY_VALUES.includes(entry.category), `${entry.rule_key} has invalid category: ${entry.category}`);
+  }
+});
+
+test('RULE_KEYS.size === RULE_CATALOGUE.length (== 12) — pinned by doc-consistency', () => {
+  assert.equal(RULE_KEYS.size, RULE_CATALOGUE.length);
+  assert.equal(RULE_CATALOGUE.length, 12);
+});
+
+test('getRule — returns frozen entry on hit, null on miss, null on bad input', () => {
+  const hit = getRule('UNIMPLEMENTED_CRITERION');
+  assert.ok(hit !== null);
+  assert.equal(hit.severity, 'BLOCKER');
+  assert.throws(() => { hit.severity = 'MINOR'; }); // frozen
+  assert.equal(getRule('NOPE'), null);
+  assert.equal(getRule(undefined), null);
+  assert.equal(getRule(123), null);
+});