feat: add rules engine with dynamic rule loading from rules/ directory

- Rule system: types, loader, engine in src/rules/
- Rules loaded dynamically from rules/*.ts at startup
- 5 rule files by category: validity, media, spam, content, scoring
- Rule severities: reject (instant invalid), require, penalize, flag
- Rules evaluated in pipeline before LLM gate, results injected into LLM prompt
- API endpoints: GET /api/v1/rules (list), POST /api/v1/rules/reload (hot-reload)
- formatRulesForPrompt() passes rule results to LLM for consideration

Author: echobt

rules/content.ts

@@ -0,0 +1,52 @@
+/**
+ * Content quality rules — structural and content quality checks.
+ *
+ * Category: content
+ * Evaluated alongside validity rules.
+ */
+
+import type { Rule } from '../src/rules/types.js';
+
+const rules: Rule[] = [
+  {
+    id: 'content.no-profanity',
+    description: 'Issue should not contain excessive profanity or abusive language',
+    category: 'content',
+    severity: 'flag',
+    failureMessage: 'Issue contains potentially abusive language.',
+    evaluate: (ctx) => {
+      const profanity = ['fuck', 'shit', 'damn', 'idiot', 'stupid'];
+      const lower = (ctx.title + ' ' + ctx.body).toLowerCase();
+      const count = profanity.reduce(
+        (acc, word) => acc + (lower.split(word).length - 1),
+        0,
+      );
+      return count < 3;
+    },
+  },
+  {
+    id: 'content.reasonable-length',
+    description: 'Issue body should not exceed 15000 characters (possible spam dump)',
+    category: 'content',
+    severity: 'flag',
+    failureMessage: 'Issue body is excessively long (> 15000 chars), which may indicate pasted logs or spam.',
+    evaluate: (ctx) => ctx.body.length <= 15000,
+  },
+  {
+    id: 'content.has-context',
+    description: 'Issue should mention the affected page, component, or URL',
+    category: 'content',
+    severity: 'penalize',
+    weight: 0.2,
+    failureMessage: 'Issue does not reference a specific page, URL, or component where the bug occurs.',
+    evaluate: (ctx) => {
+      const lower = ctx.body.toLowerCase();
+      const hasUrl = /https?:\/\//.test(ctx.body);
+      const hasPage = /page|screen|component|section|tab|modal|button|form|menu/.test(lower);
+      const hasRoute = /\/[a-z]/.test(ctx.body);
+      return hasUrl || hasPage || hasRoute;
+    },
+  },
+];
+
+export default rules;

rules/media.ts

@@ -0,0 +1,45 @@
+/**
+ * Media rules — evidence requirements for bounty issues.
+ *
+ * Category: media
+ * Evaluated after the media check phase.
+ */
+
+import type { Rule } from '../src/rules/types.js';
+
+const rules: Rule[] = [
+  {
+    id: 'media.require-evidence',
+    description: 'Issue must include at least one screenshot or video URL',
+    category: 'media',
+    severity: 'require',
+    failureMessage: 'No media evidence found. Attach a screenshot or video showing the bug.',
+    evaluate: (ctx) => ctx.mediaUrls.length > 0,
+  },
+  {
+    id: 'media.must-be-accessible',
+    description: 'All media URLs must be publicly accessible (HTTP 200)',
+    category: 'media',
+    severity: 'require',
+    failureMessage: 'Media URLs are not accessible. Ensure images/videos are publicly viewable.',
+    evaluate: (ctx) => {
+      if (ctx.mediaUrls.length === 0) return true;
+      return ctx.mediaAccessible;
+    },
+  },
+  {
+    id: 'media.no-placeholder-urls',
+    description: 'Media URLs should not be placeholder or example URLs',
+    category: 'media',
+    severity: 'reject',
+    failureMessage: 'Detected placeholder/example media URLs instead of real evidence.',
+    evaluate: (ctx) => {
+      const placeholders = ['example.com', 'placeholder', 'lorem', 'test.png', 'screenshot.png'];
+      return !ctx.mediaUrls.some((url) =>
+        placeholders.some((p) => url.toLowerCase().includes(p)),
+      );
+    },
+  },
+];
+
+export default rules;

rules/scoring.ts

@@ -0,0 +1,31 @@
+/**
+ * Scoring adjustment rules — modify the final score based on heuristics.
+ *
+ * Category: scoring
+ * These apply penalty weights that the engine sums into penaltyScore.
+ */
+
+import type { Rule } from '../src/rules/types.js';
+
+const rules: Rule[] = [
+  {
+    id: 'scoring.duplicate-threshold',
+    description: 'Penalize issues with moderate duplicate similarity (0.5-0.75)',
+    category: 'scoring',
+    severity: 'penalize',
+    weight: 0.3,
+    failureMessage: 'Issue has moderate similarity to existing issues, suggesting partial overlap.',
+    evaluate: (ctx) => ctx.duplicateScore < 0.5,
+  },
+  {
+    id: 'scoring.suspicious-edits',
+    description: 'Penalize issues with concerning edit history (fraud score > 0.3)',
+    category: 'scoring',
+    severity: 'penalize',
+    weight: 0.25,
+    failureMessage: 'Issue has a concerning edit history pattern.',
+    evaluate: (ctx) => ctx.editFraudScore < 0.3,
+  },
+];
+
+export default rules;

rules/spam.ts

@@ -0,0 +1,67 @@
+/**
+ * Spam rules — patterns that indicate fraudulent or low-quality submissions.
+ *
+ * Category: spam
+ * Evaluated after the spam scoring phase.
+ */
+
+import type { Rule } from '../src/rules/types.js';
+
+const rules: Rule[] = [
+  {
+    id: 'spam.high-score-reject',
+    description: 'Reject issues with spam score above 0.85',
+    category: 'spam',
+    severity: 'reject',
+    failureMessage: 'Issue has a very high spam score (> 0.85), indicating template-farmed or automated content.',
+    evaluate: (ctx) => ctx.spamScore < 0.85,
+  },
+  {
+    id: 'spam.generic-title',
+    description: 'Title should not be a generic/template title',
+    category: 'spam',
+    severity: 'penalize',
+    weight: 0.4,
+    failureMessage: 'Issue title appears to be generic or template-generated.',
+    evaluate: (ctx) => {
+      const generic = [
+        'bug found', 'bug report', 'issue found', 'error found',
+        'problem found', 'bug', 'error', 'issue', 'problem',
+        'found a bug', 'found an issue', 'found error',
+      ];
+      return !generic.includes(ctx.title.trim().toLowerCase());
+    },
+  },
+  {
+    id: 'spam.body-is-title-repeat',
+    description: 'Body should not be a simple repetition of the title',
+    category: 'spam',
+    severity: 'penalize',
+    weight: 0.5,
+    failureMessage: 'Issue body is essentially a copy of the title with no additional detail.',
+    evaluate: (ctx) => {
+      const titleNorm = ctx.title.toLowerCase().replace(/[^a-z0-9]/g, '');
+      const bodyNorm = ctx.body.toLowerCase().replace(/[^a-z0-9]/g, '');
+      if (bodyNorm.length === 0) return false;
+      return titleNorm !== bodyNorm && !bodyNorm.startsWith(titleNorm);
+    },
+  },
+  {
+    id: 'spam.no-ai-filler',
+    description: 'Body should not contain obvious AI-generated filler phrases',
+    category: 'spam',
+    severity: 'flag',
+    failureMessage: 'Issue body contains phrases typical of AI-generated filler content.',
+    evaluate: (ctx) => {
+      const aiPhrases = [
+        'as an ai', 'i cannot', 'delve into', 'it is important to note',
+        'in conclusion,', 'furthermore,', 'in summary,',
+        'this comprehensive', 'it\'s worth noting',
+      ];
+      const lower = ctx.body.toLowerCase();
+      return !aiPhrases.some((p) => lower.includes(p));
+    },
+  },
+];
+
+export default rules;

rules/validity.ts

@@ -0,0 +1,63 @@
+/**
+ * Validity rules — basic requirements for a bounty issue to be considered.
+ *
+ * Category: validity
+ * These are evaluated first in the pipeline.
+ */
+
+import type { Rule } from '../src/rules/types.js';
+
+const rules: Rule[] = [
+  {
+    id: 'validity.min-body-length',
+    description: 'Issue body must be at least 50 characters',
+    category: 'validity',
+    severity: 'reject',
+    failureMessage: 'Issue body is too short (< 50 characters). A valid bug report needs a proper description.',
+    evaluate: (ctx) => ctx.body.trim().length >= 50,
+  },
+  {
+    id: 'validity.min-title-length',
+    description: 'Issue title must be at least 10 characters',
+    category: 'validity',
+    severity: 'reject',
+    failureMessage: 'Issue title is too short (< 10 characters). Use a descriptive title.',
+    evaluate: (ctx) => ctx.title.trim().length >= 10,
+  },
+  {
+    id: 'validity.no-empty-body',
+    description: 'Issue body must not be empty or only whitespace',
+    category: 'validity',
+    severity: 'reject',
+    failureMessage: 'Issue body is empty. Provide a description with steps to reproduce.',
+    evaluate: (ctx) => ctx.body.trim().length > 0,
+  },
+  {
+    id: 'validity.has-steps-or-description',
+    description: 'Issue body should contain structured content (steps, expected/actual behavior)',
+    category: 'validity',
+    severity: 'penalize',
+    weight: 0.3,
+    failureMessage: 'Issue body lacks structured steps to reproduce or expected/actual behavior description.',
+    evaluate: (ctx) => {
+      const lower = ctx.body.toLowerCase();
+      const hasSteps = /step|reproduce|how to|1\.|2\.|3\.|\d\)/.test(lower);
+      const hasBehavior = /expect|actual|should|instead|but|however/.test(lower);
+      return hasSteps || hasBehavior;
+    },
+  },
+  {
+    id: 'validity.not-a-feature-request',
+    description: 'Issue should describe a bug, not a feature request',
+    category: 'validity',
+    severity: 'flag',
+    failureMessage: 'Issue appears to be a feature request rather than a bug report.',
+    evaluate: (ctx) => {
+      const lower = (ctx.title + ' ' + ctx.body).toLowerCase();
+      const featureSignals = ['feature request', 'suggestion', 'it would be nice', 'please add', 'can you add'];
+      return !featureSignals.some((s) => lower.includes(s));
+    },
+  },
+];
+
+export default rules;

src/index.ts

@@ -28,6 +28,7 @@ import { startRequeueRecovery, stopRequeueRecovery } from './queue/requeue-recov
 import { getIssue } from './github/client.js';
 import { handleRequeue, handleForceRelease } from './api/requeue.js';
 import { getProcessingStatus, getDeadLetterList, recoverDeadLetterItem } from './api/status.js';
+import { loadRules } from './rules/index.js';
 
 /**
  * Ensure the data directory exists for SQLite persistence.
@@ -209,6 +210,53 @@ export function createApp(): express.Express {
     }
   });
 
+  // POST /api/v1/rules/reload — hot-reload rules from disk
+  apiRouter.post('/rules/reload', (_req, res) => {
+    import('./rules/index.js')
+      .then((mod) => mod.reloadRules())
+      .then((reloaded) => {
+        logger.info({ count: reloaded.length }, 'Rules hot-reloaded');
+        res.status(200).json({
+          status: 'reloaded',
+          count: reloaded.length,
+          rules: reloaded.map((r) => ({
+            id: r.id,
+            category: r.category,
+            severity: r.severity,
+            enabled: r.enabled !== false,
+          })),
+        });
+      })
+      .catch((err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error({ err: msg }, 'Rules reload failed');
+        res.status(500).json({ error: 'reload_failed', message: msg });
+      });
+  });
+
+  // GET /api/v1/rules — list loaded rules
+  apiRouter.get('/rules', (_req, res) => {
+    import('./rules/index.js')
+      .then((mod) => {
+        const rules = mod.getRules();
+        res.status(200).json({
+          count: rules.length,
+          rules: rules.map((r) => ({
+            id: r.id,
+            category: r.category,
+            severity: r.severity,
+            description: r.description,
+            enabled: r.enabled !== false,
+            weight: r.weight ?? 1.0,
+          })),
+        });
+      })
+      .catch((err: unknown) => {
+        const msg = err instanceof Error ? err.message : String(err);
+        res.status(500).json({ error: 'rules_error', message: msg });
+      });
+  });
+
   app.use('/api/v1', apiRouter);
 
   return app;
@@ -270,6 +318,10 @@ async function main(): Promise<void> {
     }
   });
 
+  // Load validation rules from rules/*.ts
+  const rules = await loadRules();
+  logger.info({ count: rules.length }, 'Validation rules loaded');
+
   // Start background services
   startPoller();
   startQueueProcessor();