loreli 0.0.0 → 1.0.0

package/packages/knowledge/README.md

@@ -0,0 +1,237 @@
+# loreli/knowledge
+
+Knowledge capture engine — the write path. Classifies review and plan feedback, detects recurring patterns across PRs and discussions, proposes promotions via GitHub Discussions with smart target suggestions, and applies approved promotions by creating action issues.
+
+## Overview
+
+The knowledge package closes the feedback loop in Loreli's agentic workflow. Review comments and plan verdict feedback are classified into categories, aggregated across PRs and discussions, and when recurring patterns emerge, promoted into permanent standards — AGENTS.md, custom prompts, or other configuration.
+
+```text
+classify → patterns → propose → [human approval] → apply
+```
+
+Feedback is captured from two sources:
+
+- **PR reviews** — `forward()` in `loreli/review` classifies `REQUEST_CHANGES` feedback and posts a `loreli:feedback` marker with `source="pr"` on the PR.
+- **Plan verdicts** — The `plan/verdict` action classifies `changes-requested` feedback and posts a `loreli:feedback` marker with `source="plan"` on the discussion.
+
+## API Reference
+
+### `classify(feedback, opts?)`
+
+Categorize feedback text into a category using keyword heuristics. Each category has a set of regex patterns (see [Configuration](#configuration) for the full list). The text is scored against every allowed category, and the highest-scoring category wins.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `feedback` | `string` | Review or verdict comment text. |
+| `opts.categories` | `string[]` | Restrict classification to only these categories. When provided, categories not in this list are never scored — even if the text contains matching keywords. Defaults to all six built-in categories. |
+
+**Returns:** `{ category: string, confidence: number }`
+
+- `category` — The highest-scoring category from the allowed set. When no keywords match anything, defaults to `documentation`.
+- `confidence` — `0` to `1`. Each keyword match adds `1/3` to confidence (capped at `1.0`). Zero means no keywords matched.
+
+The following example classifies a review comment about naming conventions:
+
+```js
+import { classify } from 'loreli/knowledge';
+
+const { category, confidence } = classify(
+  'The naming convention should follow camelCase for consistency'
+);
+// category: 'naming', confidence: 0.67
+```
+
+When categories are restricted, matching keywords outside the allowed set are ignored. This is how the `feedback.categories` config restricts what gets captured during PR reviews:
+
+```js
+classify('Missing test coverage', { categories: ['naming', 'security'] });
+// category: 'naming' (or 'security'), confidence: 0
+// 'testing' keywords match but 'testing' is not in the allowed list
+```
+
+### `patterns(hub, repo, opts?)`
+
+Scan `loreli:feedback` markers across PR comments and discussion comments to detect recurring patterns above a configurable threshold.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `hub` | `object` | Hub instance with `searchIssues`, `comments`, `category`, `discussions`, and `discussionComments` methods. |
+| `repo` | `string` | `"owner/name"` repository. |
+| `opts.threshold` | `number` | Minimum occurrences to report a pattern. Default: `5`. |
+| `opts.category` | `string` | Filter to a specific category. |
+
+**Returns:** `Promise<Array<Pattern>>`
+
+Each pattern has the shape:
+
+```ts
+{
+  summary: string,
+  category: string,
+  count: number,
+  fingerprint: string,
+  providers: Record<string, number>,
+  refs: Array<{
+    ref: string,
+    type: 'pr' | 'discussion',
+    excerpt: string,
+    provider: string
+  }>
+}
+```
+
+The `type` discriminator on each ref distinguishes whether the feedback originated from a PR review (`source="pr"`) or a plan verdict (`source="plan"`).
+
+Cross-provider patterns (multiple providers flagging the same category) lower the effective threshold by 1.
+
+### `propose(hub, repo, pattern)`
+
+Create a promotion discussion for a detected pattern. The discussion is created in the repo's "Loreli" discussion category with a `loreli:promotion` marker and a structured template.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `hub` | `object` | Hub instance with `category` and `discuss` methods. |
+| `repo` | `string` | `"owner/name"` repository. |
+| `pattern` | `Pattern` | A pattern object from `patterns()`. |
+
+**Returns:** `Promise<{ number: number, id: string, url: string }>`
+
+The generated discussion body includes:
+
+1. **Smart target suggestion** — The most likely promotion target is pre-checked based on feedback source distribution:
+   - Discussion-dominated feedback suggests the **Planner prompt** (`.loreli/planner.md`)
+   - PR-dominated feedback suggests the **Action prompt** (`.loreli/action.md`)
+   - Evenly mixed feedback suggests **AGENTS.md**
+2. **Mixed ref formatting** — Refs are prefixed with `PR #N` or `Discussion #N` based on their type.
+3. **Clear human instructions** — The Decision section tells the human to check one option and close the discussion to trigger the promotion pipeline.
+
+Available promotion targets:
+
+| Target | File Path | Use Case |
+|--------|-----------|----------|
+| AGENTS.md | `AGENTS.md` | Universal coding convention |
+| Planner prompt | `.loreli/planner.md` | Planning standards |
+| Reviewer prompt | `.loreli/review.md` | Review criteria |
+| Action prompt | `.loreli/action.md` | Implementation guidance |
+| Risk prompt | `.loreli/risk.md` | Risk assessment criteria |
+
+### `apply(hub, repo, promotion)`
+
+Execute an approved promotion by creating an action issue. Parses the selected target checkbox from the promotion discussion body and includes the concrete file path in the issue.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `hub` | `object` | Hub instance with `open` method. |
+| `repo` | `string` | `"owner/name"` repository. |
+| `promotion.summary` | `string` | Pattern summary for the issue title. |
+| `promotion.discussion` | `number` | Source discussion number. |
+| `promotion.body` | `string` | Full promotion discussion body (used to extract the selected target). |
+
+**Returns:** `Promise<{ number: number, url: string }>`
+
+The created issue includes a `## Target` section with `**Target file**` pointing to the concrete path (e.g., `.loreli/action.md`), a `## Change` section with the promotion body, and a `## Reference` linking back to the discussion.
+
+If no target checkbox is checked, defaults to `AGENTS.md`.
+
+### `extractRefs(comments)`
+
+Extract unique `#N` references from discussion comment bodies.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `comments` | `Array<{ body: string }>` | Discussion comments. |
+
+**Returns:** `number[]` — Unique referenced numbers.
+
+### `classifyRefs(comments, refs)`
+
+Classify extracted references as blockers or informational using keyword heuristics (e.g., "blocked by #N", "depends on #N").
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `comments` | `Array<{ body: string, author?: string }>` | Discussion comments containing the refs. |
+| `refs` | `number[]` | Extracted reference numbers from `extractRefs()`. |
+
+**Returns:** `{ blockers: number[], references: number[] }`
+
+## Feedback Marker Format
+
+The `loreli:feedback` marker is an HTML comment embedded in PR or discussion comments:
+
+```html
+<!-- loreli:feedback category="testing" confidence="0.67" provider="openai" source="plan" -->
+```
+
+| Attribute | Description |
+|-----------|-------------|
+| `category` | Classification category (naming, architecture, testing, documentation, performance, security). |
+| `confidence` | Classification confidence from `0.00` to `1.00`. |
+| `provider` | LLM provider that generated the feedback (e.g., `openai`, `anthropic`). |
+| `source` | Feedback origin: `pr` (PR review) or `plan` (plan verdict). |
+
+## Human Approval Workflow
+
+1. **Detection** — The `knowledge` reactor in `start.js` calls `patterns()` each tick. When a category crosses the threshold, `propose()` creates a promotion discussion.
+2. **Review** — Repo maintainers receive a GitHub notification. The discussion shows the recurring pattern with PR/discussion references, cross-provider consensus, and a suggested promotion target.
+3. **Decision** — The human checks one of: `[x] Approve` or `[x] Reject`, then **closes the discussion**.
+4. **Execution** — The `promotion-apply` reactor detects the closed, approved discussion and calls `apply()`, which creates an action issue targeting the selected file. An action agent picks up the issue and implements the change.
+
+## Configuration
+
+```yaml
+# loreli.yml
+feedback:
+  enabled: true
+  threshold: 5
+  categories:
+    - naming
+    - architecture
+    - testing
+    - documentation
+    - performance
+    - security
+```
+
+### How each setting affects the system
+
+**`enabled`** — Master switch. When `false`, no `loreli:feedback` markers are posted during PR reviews (`forward()` in `loreli/review` checks this before calling `classify()`). Plan verdict classification in `plan/verdict` does not check this flag because the MCP tool context lacks config access. Pattern detection and promotion reactors also check this flag before running.
+
+**`threshold`** — The minimum number of `loreli:feedback` markers in a single category before `patterns()` reports it as a recurring pattern. A pattern with 4 occurrences in a system configured with `threshold: 5` is invisible to the promotion pipeline. Cross-provider consensus (multiple LLM providers flagging the same category) lowers the effective threshold by 1, so a cross-provider pattern needs only 4 occurrences at the default threshold.
+
+**`categories`** — The list of categories that `classify()` is allowed to score against during PR review feedback capture. This acts as a **gate at the capture stage**: removing a category from this list means PR review feedback matching that category will never produce a `loreli:feedback` marker, which transitively means `patterns()` will never detect patterns in that category from PRs, and `propose()` will never create a promotion discussion for it.
+
+The six built-in categories and what they detect:
+
+| Category | Keywords | What it captures |
+|----------|----------|------------------|
+| `naming` | name, rename, prefix, convention, camelCase | Naming convention violations and style inconsistencies |
+| `architecture` | architect, structure, module, package, refactor, decouple | Structural concerns, module boundaries, coupling issues |
+| `testing` | test, coverage, assert, fixture, TDD, mock | Missing tests, inadequate coverage, testing methodology |
+| `documentation` | docs, document, README, JSDoc, comment, explain | Missing or incomplete documentation |
+| `performance` | perform, optimize, slow, memory, N+1, cache | Performance issues, optimization opportunities |
+| `security` | secure, secret, token, auth, vulnerable, inject | Security vulnerabilities, credential exposure, auth issues |
+
+Categories cannot be extended via config — the keyword patterns are hardcoded in `KEYWORDS`. To add a new category, add an entry to `KEYWORDS` in `packages/knowledge/src/index.js` and include it in the `feedback.categories` default in `packages/config/src/defaults.js`.
+
+Plan verdict classification (`plan/verdict` in `packages/mcp/src/tools/github.js`) uses all hardcoded categories regardless of the config list, because the MCP tool context does not have access to the orchestrator config. This means plan feedback is always classified against all six categories even if the config restricts PR feedback to a subset.
+
+## Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `category: not implemented` | Hub instance lacks the `category()` method. | Ensure the hub is a `GitHubHub` instance, not the base stub. |
+| `discussions: not implemented` | Hub instance lacks the `discussions()` method. | Same as above. |
+| Non-fatal catch blocks | Individual PR/discussion comment fetches may fail due to permissions or rate limits. | Patterns are still reported from successful fetches. Check GitHub token scopes if patterns seem incomplete. |

package/packages/knowledge/src/index.js

@@ -0,0 +1,412 @@
+/**
+ * Knowledge capture engine — the write path.
+ *
+ * Classifies review feedback, detects recurring patterns across PRs,
+ * proposes promotions via GitHub Discussions, and applies approved
+ * promotions by creating issues.
+ *
+ * @module loreli/knowledge
+ */
+
+import { mark, parse } from 'loreli/marker';
+import { logger } from 'loreli/log';
+import { createHash } from 'node:crypto';
+
+const log = logger('knowledge');
+
+/**
+ * Keyword patterns for heuristic feedback classification.
+ * Each entry maps a category to an array of regex patterns.
+ *
+ * @type {Record<string, RegExp[]>}
+ */
+const KEYWORDS = {
+  naming: [/\bnam(e|ing)\b/i, /\brename\b/i, /\bprefix\b/i, /\bconvention\b/i, /\bcamelCase\b/i],
+  architecture: [/\barchitect/i, /\bstructur/i, /\bmodule\b/i, /\bpackage\b/i, /\brefactor/i, /\bdecouple/i],
+  testing: [/\btest/i, /\bcoverage\b/i, /\bassert/i, /\bfixture/i, /\bTDD\b/i, /\bmock\b/i],
+  documentation: [/\bdoc(s|ument)/i, /\bREADME\b/i, /\bJSDoc\b/i, /\bcomment/i, /\bexplain/i],
+  performance: [/\bperform/i, /\boptimiz/i, /\bslow\b/i, /\bmemory\b/i, /\bN\+1\b/i, /\bcache\b/i],
+  security: [/\bsecur/i, /\bsecret/i, /\btoken\b/i, /\bauth/i, /\bvulnerab/i, /\binject/i]
+};
+
+/**
+ * Classify review feedback text into a category using keyword heuristics.
+ *
+ * @param {string} feedback - Review comment text.
+ * @param {object} [opts] - Options.
+ * @param {string[]} [opts.categories] - Allowed categories (defaults to all).
+ * @returns {{category: string, confidence: number}}
+ */
+export function classify(feedback, opts = {}) {
+  const allowed = opts.categories ?? Object.keys(KEYWORDS);
+  const scores = {};
+
+  for (const cat of allowed) {
+    const patterns = KEYWORDS[cat];
+    if (!patterns) continue;
+    scores[cat] = 0;
+    for (const re of patterns) {
+      if (re.test(feedback)) scores[cat]++;
+    }
+  }
+
+  let best = 'documentation';
+  let max = 0;
+  for (const [cat, score] of Object.entries(scores)) {
+    if (score > max) {
+      max = score;
+      best = cat;
+    }
+  }
+
+  const confidence = max > 0 ? Math.min(max / 3, 1) : 0;
+  return { category: best, confidence };
+}
+
+/**
+ * Compute a stable fingerprint for a pattern summary.
+ *
+ * @param {string} summary - Pattern summary text.
+ * @returns {string} Hex digest (first 12 chars).
+ */
+function fingerprint(summary) {
+  return createHash('sha256').update(summary).digest('hex').slice(0, 12);
+}
+
+/**
+ * Scan review comments for loreli:feedback markers and detect
+ * recurring patterns above the configured threshold.
+ *
+ * @param {object} hub - Hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {object} [opts] - Options.
+ * @param {number} [opts.threshold=5] - Minimum occurrences.
+ * @param {string} [opts.category] - Filter to a specific category.
+ * @returns {Promise<Array<{summary: string, category: string, count: number, fingerprint: string, providers: Record<string, number>, refs: Array<{ref: string, type: 'pr'|'discussion', excerpt: string, provider: string}>}>>}
+ */
+export async function patterns(hub, repo, opts = {}) {
+  const threshold = opts.threshold ?? 5;
+  const buckets = {};
+
+  /**
+   * @param {string} key - Category key.
+   * @param {{ref: string, type: string, excerpt: string, provider: string}} item
+   */
+  function push(key, item) {
+    if (!buckets[key]) buckets[key] = { items: [], providers: {} };
+    buckets[key].items.push(item);
+    buckets[key].providers[item.provider] = (buckets[key].providers[item.provider] ?? 0) + 1;
+  }
+
+  const results = await hub.searchIssues(repo, 'loreli:feedback');
+  for (const item of results) {
+    if (item.type !== 'pr') continue;
+    try {
+      const comments = await hub.comments(repo, item.number);
+      for (const c of comments) {
+        const data = parse(c.body, 'feedback');
+        if (!data?.category) continue;
+        if (opts.category && data.category !== opts.category) continue;
+
+        push(data.category, {
+          ref: String(item.number),
+          type: 'pr',
+          excerpt: c.body.slice(0, 120).replace(/<!--[^>]*-->/g, '').trim(),
+          provider: data.provider ?? 'unknown'
+        });
+      }
+    } catch { /* non-fatal */ }
+  }
+
+  try {
+    const cat = await hub.category(repo, 'Loreli');
+    const discussions = await hub.discussions(repo, cat.id);
+    for (const disc of discussions) {
+      try {
+        const comments = await hub.discussionComments(disc.id);
+        for (const c of comments) {
+          const data = parse(c.body, 'feedback');
+          if (!data?.category) continue;
+          if (opts.category && data.category !== opts.category) continue;
+
+          push(data.category, {
+            ref: String(disc.number),
+            type: 'discussion',
+            excerpt: c.body.slice(0, 120).replace(/<!--[^>]*-->/g, '').trim(),
+            provider: data.provider ?? 'unknown'
+          });
+        }
+      } catch { /* non-fatal */ }
+    }
+  } catch { /* non-fatal — discussions may not be available */ }
+
+  const found = [];
+  for (const [category, bucket] of Object.entries(buckets)) {
+    if (bucket.items.length < threshold) continue;
+
+    const crossProvider = Object.keys(bucket.providers).length > 1;
+    const effective = crossProvider ? threshold - 1 : threshold;
+    if (bucket.items.length < effective) continue;
+
+    found.push({
+      summary: `${category} feedback pattern (${bucket.items.length} occurrences)`,
+      category,
+      count: bucket.items.length,
+      fingerprint: fingerprint(`${category}:${bucket.items.length}`),
+      providers: bucket.providers,
+      refs: bucket.items
+    });
+  }
+
+  return found;
+}
+
+/**
+ * Determine the suggested promotion target based on feedback source distribution.
+ *
+ * @param {Array<{type: string}>} refs - Pattern refs with type discriminator.
+ * @returns {'planner'|'action'|'agents'}
+ */
+function target(refs) {
+  const planCount = refs.filter(function isDisc(r) { return r.type === 'discussion'; }).length;
+  const prCount = refs.filter(function isPr(r) { return r.type === 'pr'; }).length;
+  if (planCount > prCount) return 'planner';
+  if (prCount > planCount) return 'action';
+  return 'agents';
+}
+
+/**
+ * Map of target keys to their display labels.
+ *
+ * @type {Record<string, string>}
+ */
+const TARGETS = {
+  agents: 'AGENTS.md -- universal coding convention',
+  planner: 'Planner prompt -- planning standards (.loreli/planner.md)',
+  reviewer: 'Reviewer prompt -- review criteria (.loreli/review.md)',
+  action: 'Action prompt -- implementation guidance (.loreli/action.md)',
+  risk: 'Risk prompt -- risk assessment criteria (.loreli/risk.md)'
+};
+
+/**
+ * Create a promotion discussion for a detected pattern.
+ *
+ * The template includes a smart target suggestion pre-checked based on
+ * feedback source distribution, mixed PR/discussion ref formatting, and
+ * clear human instructions for the decision workflow.
+ *
+ * @param {object} hub - Hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {object} pattern - Pattern from patterns().
+ * @returns {Promise<{number: number, id: string, url: string}>}
+ */
+export async function propose(hub, repo, pattern) {
+  const fp = pattern.fingerprint;
+  const providerLine = Object.entries(pattern.providers)
+    .map(function fmt([p, n]) { return `${p} (${n})`; })
+    .join(', ');
+
+  const refs = pattern.refs
+    .map(function fmt(r) {
+      const prefix = r.type === 'discussion' ? 'Discussion' : 'PR';
+      return `- ${prefix} #${r.ref}: "${r.excerpt}"`;
+    })
+    .join('\n');
+
+  const suggested = target(pattern.refs);
+  const targetCheckboxes = Object.entries(TARGETS)
+    .map(function fmt([key, label]) {
+      const checked = key === suggested ? 'x' : ' ';
+      return `- [${checked}] ${label}`;
+    })
+    .join('\n');
+
+  const body = [
+    mark('promotion', { fingerprint: fp, category: pattern.category, status: 'pending' }),
+    '',
+    '## Pattern',
+    '',
+    `This review feedback appeared in ${pattern.count} reviews:`,
+    refs,
+    '',
+    `**Category**: ${pattern.category}`,
+    `**Providers**: ${providerLine}`,
+    '',
+    '## Proposed Promotion',
+    '',
+    'Select the promotion target (suggested target is pre-selected based on feedback source):',
+    '',
+    targetCheckboxes,
+    '',
+    '> _Describe the rule or convention to promote here._',
+    '',
+    '## Decision',
+    '',
+    'Check **one** option below, then **close this discussion** to trigger the promotion pipeline.',
+    '',
+    '- [ ] Approve -- apply this as a standard',
+    '- [ ] Reject -- this is a preference, not a standard',
+    '',
+    '> Closing without checking a box takes no action. The discussion can be reopened to reconsider.'
+  ].join('\n');
+
+  const cat = await hub.category(repo, 'Loreli');
+  const disc = await hub.discuss(repo, {
+    title: `Promotion: ${pattern.summary}`,
+    body,
+    categoryId: cat.id,
+    repositoryId: cat.repositoryId
+  });
+
+  log.info(`propose: created promotion discussion #${disc.number} for ${pattern.category}`);
+  return disc;
+}
+
+/**
+ * Map of target checkbox labels to concrete file paths.
+ *
+ * @type {Record<string, string>}
+ */
+const TARGET_FILES = {
+  'AGENTS.md': 'AGENTS.md',
+  'Planner prompt': '.loreli/planner.md',
+  'Reviewer prompt': '.loreli/review.md',
+  'Action prompt': '.loreli/action.md',
+  'Risk prompt': '.loreli/risk.md'
+};
+
+/**
+ * Parse the selected target from a promotion discussion body by finding
+ * the first checked checkbox (`- [x]`) that matches a known target label.
+ *
+ * @param {string} body - Promotion discussion body.
+ * @returns {{label: string, file: string}}
+ */
+function extractTarget(body) {
+  const checked = /- \[x\] (\w[\w\s]*?)(?:\s+--|\s*$)/gm;
+  let m;
+  while ((m = checked.exec(body)) !== null) {
+    const label = m[1].trim();
+    if (TARGET_FILES[label]) return { label, file: TARGET_FILES[label] };
+  }
+  return { label: 'AGENTS.md', file: 'AGENTS.md' };
+}
+
+/**
+ * Execute an approved promotion by creating an action issue.
+ *
+ * Parses the selected promotion target from the discussion body and
+ * includes the concrete file path in the action issue so the
+ * implementing agent knows exactly which file to update.
+ *
+ * @param {object} hub - Hub instance.
+ * @param {string} repo - "owner/name" repository.
+ * @param {object} promotion - Promotion data.
+ * @param {string} promotion.summary - Pattern summary.
+ * @param {number} promotion.discussion - Discussion number.
+ * @param {string} promotion.body - Full promotion discussion body.
+ * @returns {Promise<{number: number, url: string}>}
+ */
+export async function apply(hub, repo, promotion) {
+  const { label, file } = extractTarget(promotion.body);
+
+  const body = [
+    `Apply the approved promotion from discussion #${promotion.discussion}.`,
+    '',
+    '## Target',
+    '',
+    `**Target file**: \`${file}\``,
+    `**Selected by**: ${label}`,
+    '',
+    '## Change',
+    '',
+    promotion.body,
+    '',
+    '## Reference',
+    '',
+    `Promotion discussion: #${promotion.discussion}`
+  ].join('\n');
+
+  const issue = await hub.open(repo, {
+    title: `Apply promotion: ${promotion.summary}`,
+    body,
+    labels: ['loreli', 'loreli:action']
+  });
+
+  log.info(`apply: created action issue #${issue.number} for promotion from #${promotion.discussion}`);
+  return issue;
+}
+
+/**
+ * Blocker signal patterns (case-insensitive). #REF is replaced with the
+ * actual #N reference when testing. A ref matches as a blocker if any
+ * pattern matches the joined comment text.
+ *
+ * @type {RegExp[]}
+ */
+const BLOCKER_SIGNALS = [
+  /\bneed(?:s|ed)?\b.*#REF\b/i,
+  /\bblock(?:s|ed|ing)?\s+(?:by\s+)?#REF\b/i,
+  /\bdepend(?:s|ing)?\s+on\s+#REF\b/i,
+  /\bwait(?:s|ing)?\s+(?:for|on)\s+#REF\b/i,
+  /\brequir(?:es?|ing)\b.*#REF\b/i,
+  /\bprerequisite\b.*#REF\b/i,
+  /\bafter\s+#REF\s+(?:is\s+)?(?:resolved|merged|closed)/i,
+  /\bbefore\s+(?:we|this)\s+can\b.*#REF\b/i,
+  /\bcan(?:no|')?t\s+(?:proceed|start|continue)\b.*#REF\b/i
+];
+
+/**
+ * Extract unique issue/PR number references from discussion comments.
+ * Matches `#N` patterns in comment bodies.
+ *
+ * @param {Array<{body: string, author?: string}>} comments - Discussion comments.
+ * @returns {number[]} Unique referenced numbers.
+ */
+export function extractRefs(comments) {
+  const refs = new Set();
+  for (const c of comments) {
+    for (const m of c.body.matchAll(/#(\d+)/g)) refs.add(Number(m[1]));
+  }
+  return [...refs];
+}
+
+/**
+ * Classify issue/PR references as blockers or informational using keyword
+ * heuristics. For each ref, scans the comment text around that ref for
+ * blocker signal patterns. Returns structured classification so the caller
+ * can verify blockers against the hub before parking a discussion.
+ *
+ * @param {Array<{body: string, author?: string}>} comments - Discussion comments containing the refs.
+ * @param {number[]} refs - Extracted reference numbers.
+ * @returns {{blockers: number[], references: number[]}}
+ */
+export function classifyRefs(comments, refs) {
+  if (!refs.length) return { blockers: [], references: [] };
+
+  const text = comments.map(function format(c) {
+    return c.author ? `${c.author}: ${c.body}` : c.body;
+  }).join('\n');
+
+  const blockers = [];
+  const references = [];
+
+  for (const ref of refs) {
+    const refStr = '#' + ref;
+    let isBlocker = false;
+
+    for (const pattern of BLOCKER_SIGNALS) {
+      const source = pattern.source.replace(/#REF\b/g, refStr);
+      const re = new RegExp(source, pattern.flags);
+      if (re.test(text)) {
+        isBlocker = true;
+        break;
+      }
+    }
+
+    if (isBlocker) blockers.push(ref);
+    else references.push(ref);
+  }
+
+  return { blockers, references };
+}