loreli 1.0.0 → 2.0.0

package/packages/agent/src/discover.js

@@ -0,0 +1,396 @@
+import { execFile as execFileCb } from 'node:child_process';
+import { promisify } from 'node:util';
+import { logger } from 'loreli/log';
+import { defaults } from 'loreli/config';
+
+const execFile = promisify(execFileCb);
+const log = logger('discover');
+
+const PROXY_BACKENDS = [
+  {
+    backend: 'claude',
+    baseKey: 'ANTHROPIC_BASE_URL',
+    keyOrder: ['ANTHROPIC_API_KEY', 'OPENAI_API_KEY']
+  },
+  {
+    backend: 'codex',
+    baseKey: 'OPENAI_BASE_URL',
+    keyOrder: ['OPENAI_API_KEY', 'ANTHROPIC_API_KEY']
+  }
+];
+
+/**
+ * Known tiers in priority order (lowest capability first).
+ * @type {string[]}
+ */
+const TIERS = ['fast', 'balanced', 'powerful'];
+
+/**
+ * Detect AI provider from a cursor-agent model ID.
+ *
+ * @param {string} id - Model identifier.
+ * @returns {'openai'|'anthropic'|null} Provider, or null for unsupported models.
+ */
+function provider(id) {
+  if (/^(gpt-|o[134]|codex-)/.test(id)) return 'openai';
+  if (/^(opus-|sonnet-|haiku-|claude-)/.test(id)) return 'anthropic';
+  return null;
+}
+
+/**
+ * Read an env value with config override precedence.
+ *
+ * @param {object|undefined} config - Config instance with `get()`.
+ * @param {string} backend - Backend name.
+ * @param {string} key - Env key name.
+ * @returns {string|undefined} Resolved env value.
+ */
+function envValue(config, backend, key) {
+  const fromConfig = config?.get?.(`backends.${backend}.env.${key}`);
+  if (typeof fromConfig === 'string' && fromConfig.length) return fromConfig;
+  const fromProcess = process.env[key];
+  if (typeof fromProcess === 'string' && fromProcess.length) return fromProcess;
+  return undefined;
+}
+
+/**
+ * Resolve timeout for proxy model discovery.
+ *
+ * @param {object|undefined} config - Config instance with `get()`.
+ * @returns {number} Timeout in milliseconds.
+ */
+function proxyTimeout(config) {
+  const configured = config?.get?.('timeouts.proxyDiscovery');
+  if (typeof configured === 'number' && configured > 0) return configured;
+  const fallback = defaults?.timeouts?.proxyDiscovery;
+  if (typeof fallback === 'number' && fallback > 0) return fallback;
+  return 5000;
+}
+
+/**
+ * Build endpoint candidates for proxy model discovery.
+ *
+ * Handles base URLs with and without `/v1` to avoid producing
+ * invalid `/v1/v1/models` paths.
+ *
+ * @param {string} baseUrl - Proxy base URL.
+ * @returns {string[]} Candidate absolute URLs in priority order.
+ */
+function endpointCandidates(baseUrl) {
+  const base = baseUrl.endsWith('/') ? baseUrl : `${baseUrl}/`;
+  const parsed = new URL(base);
+  const path = parsed.pathname.replace(/\/+$/, '');
+  const hasV1 = path.endsWith('/v1');
+  const candidates = [];
+
+  if (hasV1) {
+    candidates.push(new URL('models', base).toString());
+    candidates.push(new URL('../models', base).toString());
+  } else {
+    candidates.push(new URL('v1/models', base).toString());
+    candidates.push(new URL('models', base).toString());
+  }
+
+  return [...new Set(candidates)];
+}
+
+/**
+ * Normalize a base URL for cache keying.
+ *
+ * @param {string} baseUrl - Base URL.
+ * @returns {string} Normalized URL string.
+ */
+function normalizeBase(baseUrl) {
+  const parsed = new URL(baseUrl);
+  parsed.search = '';
+  parsed.hash = '';
+  parsed.pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+  return parsed.toString();
+}
+
+/**
+ * Query one proxy endpoint candidate for model listing.
+ *
+ * @param {string} endpoint - Candidate endpoint URL.
+ * @param {string|undefined} apiKey - Optional bearer token.
+ * @param {number} timeout - Request timeout in milliseconds.
+ * @returns {Promise<null|object[]>} Raw model objects.
+ */
+async function requestModels(endpoint, apiKey, timeout) {
+  const headers = {};
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
+
+  const response = await fetch(endpoint, {
+    headers,
+    signal: AbortSignal.timeout(timeout)
+  });
+
+  if (!response.ok) return null;
+
+  let body;
+  try {
+    body = await response.json();
+  } catch {
+    return null;
+  }
+
+  return Array.isArray(body?.data) ? body.data : null;
+}
+
+/**
+ * Convert proxy `/models` payload into internal discovery shape.
+ *
+ * Keeps all model IDs for `validate()`; provider-aware tier mapping
+ * is derived from recognizable IDs only.
+ *
+ * @param {object[]} entries - Raw model entries.
+ * @returns {{models: object[], tiers: object}|null} Discovery result.
+ */
+function toDiscovery(entries) {
+  const models = [];
+
+  for (const entry of entries) {
+    if (!entry?.id) continue;
+    const id = String(entry.id);
+    models.push({
+      id,
+      name: id,
+      provider: provider(id),
+      tier: tier(id),
+      marker: null
+    });
+  }
+
+  if (!models.length) return null;
+  return { models, tiers: tiers(models) };
+}
+
+/**
+ * Discover proxy models using endpoint candidates and optional auth.
+ *
+ * @param {string} baseUrl - Proxy base URL.
+ * @param {string|undefined} apiKey - Optional bearer token.
+ * @param {number} timeout - Request timeout in milliseconds.
+ * @returns {Promise<{models: object[], tiers: object}|null>} Discovery result.
+ */
+async function discoverProxy(baseUrl, apiKey, timeout) {
+  for (const endpoint of endpointCandidates(baseUrl)) {
+    const data = await requestModels(endpoint, apiKey, timeout);
+    if (!data) continue;
+    const discovery = toDiscovery(data);
+    if (discovery) return discovery;
+  }
+  return null;
+}
+
+/**
+ * Return unique auth key candidates in order.
+ *
+ * @param {object|undefined} config - Config instance with `get()`.
+ * @param {string} backend - Backend name.
+ * @param {string[]} order - Env key names in priority order.
+ * @returns {(string|undefined)[]} Ordered key candidates.
+ */
+function authKeys(config, backend, order) {
+  const keys = [];
+  for (const keyName of order) {
+    const value = envValue(config, backend, keyName);
+    if (value && !keys.includes(value)) keys.push(value);
+  }
+  if (!keys.length) keys.push(undefined);
+  return keys;
+}
+
+/**
+ * Patterns that force a model into a specific tier.
+ * Checked in order — first match wins.
+ * @type {Array<{pattern: RegExp, tier: string}>}
+ */
+const TIER_RULES = [
+  { pattern: /-(low|mini)\b/, tier: 'fast' },
+  { pattern: /(^|-)haiku-/, tier: 'fast' },
+  { pattern: /\bflash\b/, tier: 'fast' },
+  { pattern: /-(xhigh|max)\b/, tier: 'powerful' },
+  { pattern: /(^|-)opus-/, tier: 'powerful' },
+  { pattern: /^o3\b/, tier: 'powerful' },
+  { pattern: /-high\b/, tier: 'powerful' }
+];
+
+/**
+ * Classify a model ID into a capability tier.
+ *
+ * @param {string} id - Model identifier.
+ * @returns {string} Tier name ('fast', 'balanced', or 'powerful').
+ */
+function tier(id) {
+  for (const rule of TIER_RULES) {
+    if (rule.pattern.test(id)) return rule.tier;
+  }
+  return 'balanced';
+}
+
+/**
+ * Parse the structured output of `cursor-agent --list-models`.
+ *
+ * Each line is `id - Human Name` with optional `(default)` or `(current)` markers.
+ * Only models from supported providers (openai, anthropic) are returned.
+ *
+ * @param {string} output - Raw stdout from `cursor-agent --list-models`.
+ * @returns {Array<{id: string, name: string, provider: string, tier: string, marker: string|null}>}
+ */
+export function parseCursor(output) {
+  const models = [];
+  for (const line of output.split('\n')) {
+    const match = line.match(/^(\S+)\s+-\s+(.+?)(?:\s+\((default|current)\))?\s*$/);
+    if (!match) continue;
+
+    const [, id, name, marker] = match;
+    const p = provider(id);
+    if (!p) continue;
+
+    models.push({
+      id,
+      name: name.trim(),
+      provider: p,
+      tier: tier(id),
+      marker: marker ?? null
+    });
+  }
+  return models;
+}
+
+/**
+ * Build a tier map from a flat list of discovered models.
+ *
+ * Groups models by provider, then for each tier picks the best candidate:
+ * models marked as `default` or `current` are preferred, then the
+ * lexicographically last ID (usually the latest generation).
+ *
+ * @param {Array<{id: string, provider: string, tier: string, marker: string|null}>} models
+ * @returns {Record<string, Record<string, string>>} `{ fast: { openai: 'gpt-...', anthropic: '...' }, ... }`
+ */
+export function tiers(models) {
+  const grouped = {};
+  for (const m of models) {
+    const key = `${m.provider}:${m.tier}`;
+    if (!grouped[key]) grouped[key] = [];
+    grouped[key].push(m);
+  }
+
+  const result = {};
+  for (const t of TIERS) {
+    for (const prov of ['openai', 'anthropic']) {
+      const candidates = grouped[`${prov}:${t}`];
+      if (!candidates?.length) continue;
+
+      const best = candidates.find(function marked(m) { return m.marker; })
+        ?? candidates.sort(function latest(a, b) { return b.id.localeCompare(a.id); })[0];
+
+      if (!result[t]) result[t] = {};
+      result[t][prov] = best.id;
+    }
+  }
+  return result;
+}
+
+/**
+ * Discover available models from cursor-agent CLI.
+ *
+ * @returns {Promise<{models: object[], tiers: object}|null>} Discovery result, or null on failure.
+ */
+export async function discoverCursor() {
+  try {
+    const { stdout } = await execFile('cursor-agent', ['--list-models'], {
+      timeout: 10000,
+      maxBuffer: 64 * 1024
+    });
+
+    const models = parseCursor(stdout);
+    if (!models.length) {
+      log.warn('cursor-agent --list-models returned no supported models');
+      return null;
+    }
+
+    log.info(`cursor: discovered ${models.length} models`);
+    return { models, tiers: tiers(models) };
+  } catch (err) {
+    log.warn(`cursor model discovery failed: ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Run model discovery for all available backends.
+ *
+ * Discovery sources:
+ * - `cursor`: `cursor-agent --list-models`
+ * - `claude` / `codex`: proxy model listing when corresponding
+ *   base URLs are configured (ANTHROPIC_BASE_URL / OPENAI_BASE_URL)
+ *
+ * Results are cached on the registry for use during model resolution.
+ *
+ * @param {import('./backends/index.js').BackendRegistry} registry - Backend registry with discovered binaries.
+ * @param {object} [opts] - Discovery options.
+ * @param {object} [opts.config] - Config instance with `get()`.
+ * @returns {Promise<Map<string, {models: object[], tiers: object}>>} Per-backend discovery results.
+ */
+export async function discover(registry, opts = {}) {
+  const { config } = opts;
+  const cache = new Map();
+  const successfulProxy = new Map();
+  const timeout = proxyTimeout(config);
+
+  if (registry.discovered.has('cursor')) {
+    const result = await discoverCursor();
+    if (result) cache.set('cursor', result);
+  }
+
+  for (const def of PROXY_BACKENDS) {
+    const { backend, baseKey, keyOrder } = def;
+    if (!registry.discovered.has(backend)) continue;
+
+    const baseUrl = envValue(config, backend, baseKey);
+    if (!baseUrl) continue;
+
+    const normalized = normalizeBase(baseUrl);
+    const cached = successfulProxy.get(normalized);
+    if (cached) {
+      cache.set(backend, cached);
+      continue;
+    }
+
+    const keys = authKeys(config, backend, keyOrder);
+    let found = null;
+
+    for (const key of keys) {
+      try {
+        found = await discoverProxy(baseUrl, key, timeout);
+      } catch (err) {
+        log.warn(`${backend} proxy discovery failed: ${err.message}`);
+      }
+      if (found) break;
+    }
+
+    if (found) {
+      cache.set(backend, found);
+      successfulProxy.set(normalized, found);
+      log.info(`${backend}: discovered ${found.models.length} models via ${baseKey}`);
+    }
+  }
+
+  return cache;
+}
+
+/**
+ * Check if a resolved model ID exists in the discovered model list.
+ *
+ * @param {string} model - Resolved model identifier.
+ * @param {string} backend - Backend name.
+ * @param {Map<string, {models: object[]}>} discovered - Discovery cache.
+ * @returns {boolean} True if the model is known or discovery is unavailable.
+ */
+export function validate(model, backend, discovered) {
+  const entry = discovered?.get(backend);
+  if (!entry?.models?.length) return true;
+  return entry.models.some(function known(m) { return m.id === model; });
+}

package/packages/agent/src/factory.js

@@ -74,46 +74,51 @@ export class Factory {
     // would have an empty model while add_agent identities had the
     // resolved name — causing "unknown" in reviewer stamps.
     const config = opts.config ?? this.config;
-    const resolved = resolveModel(model, backendName, vendor(provider), config);
+    const resolved = resolveModel(model, backendName, vendor(provider), config, this.backends.models);
 
     const identity = this.identities.acquire(theme, provider, resolved, opts.taken);
 
-    // Update context.agent before prepare() and backend construction
-    // so the Codex -c flags and .mcp.json env vars have the real name
-    // instead of null. Context is mutated in-place intentionally —
-    // callers (e.g. enlist) pass the same reference and read it back.
-    if (opts.context) {
-      opts.context.agent = identity.name;
-
-      if (!opts.context.denied) {
-        opts.context.denied = config?.get?.('agents.disallowedTools') ?? [];
+    try {
+      // Update context.agent before prepare() and backend construction
+      // so the Codex -c flags and .mcp.json env vars have the real name
+      // instead of null. Context is mutated in-place intentionally —
+      // callers (e.g. enlist) pass the same reference and read it back.
+      if (opts.context) {
+        opts.context.agent = identity.name;
+
+        if (!opts.context.denied) {
+          opts.context.denied = config?.get?.('agents.disallowedTools') ?? [];
+        }
       }
-    }
 
-    let cwd = opts.cwd ?? pathFor(identity.name);
-
-    // Collect scaffold descriptors from all registered backends so
-    // workspace.prepare() and workspace.create() write configs, hooks,
-    // and files generically — no backend-specific knowledge needed.
-    const descriptors = this.backends.scaffoldAll(opts.context);
-
-    // When we have full orchestration context (repo + home), create a
-    // git worktree instead of an empty directory. This gives the agent
-    // a fully checked-out repo with zero network overhead per agent —
-    // all from a shared bare mirror.
-    if (opts.context?.repo && opts.context?.home && !opts.cwd) {
-      const url = `https://github.com/${opts.context.repo}.git`;
-      const bare = await mirror(url, { home: opts.context.home, token: opts.context.token });
-      cwd = await createWorktree(bare, 'HEAD', identity.name, undefined, opts.context, descriptors);
-      log.info(`worktree ready at ${cwd} from mirror of ${opts.context.repo}`);
-    } else {
-      await prepare(cwd, opts.context, descriptors);
-    }
+      let cwd = opts.cwd ?? pathFor(identity.name);
+
+      // Collect scaffold descriptors from all registered backends so
+      // workspace.prepare() and workspace.create() write configs, hooks,
+      // and files generically — no backend-specific knowledge needed.
+      const descriptors = this.backends.scaffoldAll(opts.context);
+
+      // When we have full orchestration context (repo + home), create a
+      // git worktree instead of an empty directory. This gives the agent
+      // a fully checked-out repo with zero network overhead per agent —
+      // all from a shared bare mirror.
+      if (opts.context?.repo && opts.context?.home && !opts.cwd) {
+        const url = `https://github.com/${opts.context.repo}.git`;
+        const bare = await mirror(url, { home: opts.context.home, token: opts.context.token });
+        cwd = await createWorktree(bare, 'HEAD', identity.name, undefined, opts.context, descriptors);
+        log.info(`worktree ready at ${cwd} from mirror of ${opts.context.repo}`);
+      } else {
+        await prepare(cwd, opts.context, descriptors);
+      }
 
-    const agentOpts = { identity, role, cwd, model, config };
-    if (opts.context) agentOpts.context = opts.context;
+      const agentOpts = { identity, role, cwd, model, config };
+      if (opts.context) agentOpts.context = opts.context;
 
-    log.info(`created ${identity.name} (${role}) via ${backendName}`);
-    return this.backends.create(backendName, agentOpts);
+      log.info(`created ${identity.name} (${role}) via ${backendName}`);
+      return this.backends.create(backendName, agentOpts);
+    } catch (err) {
+      this.identities.release(identity);
+      throw err;
+    }
   }
 }

package/packages/agent/src/models.js

@@ -1,27 +1,45 @@
 import { defaults } from 'loreli/config';
+import { validate as validateModel } from './discover.js';
+import { logger } from 'loreli/log';
+
+const log = logger('models');
 
 /**
  * Resolve a model alias to a concrete model identifier.
  *
  * Resolution order:
  *  1. Config layer: `config.get('backends.{backend}.models.{alias}.{provider}')`
- *  2. Built-in defaults: `defaults.backends[backend].models[alias][provider]`
- *  3. Pass-through: return the alias string unchanged (exact model IDs)
+ *  2. Discovery layer: runtime-discovered models classified into tiers
+ *  3. Built-in defaults: `defaults.backends[backend].models[alias][provider]`
+ *  4. Pass-through: return the alias string unchanged (exact model IDs)
+ *
+ * When discovery data is available, the resolved model is validated
+ * against the known model list. Invalid models trigger a warning and
+ * fall back to the backend's default discovered model.
  *
  * @param {string} alias - Alias ('fast', 'balanced', 'powerful') or exact model string.
  * @param {string} backend - Backend name ('claude', 'codex', 'cursor').
  * @param {string} provider - AI provider ('openai' | 'anthropic').
  * @param {object} [config] - Config instance with a `get()` method.
+ * @param {Map} [discovered] - Discovery cache from BackendRegistry.
  * @returns {string} Resolved model identifier.
  */
-export function resolve(alias, backend, provider, config) {
-  // Config layer: highest priority
+export function resolve(alias, backend, provider, config, discovered) {
   const fromConfig = config?.get?.(`backends.${backend}.models.${alias}.${provider}`);
   if (fromConfig) return fromConfig;
 
-  // Built-in defaults layer
+  const fromDiscovery = discovered?.get(backend)?.tiers?.[alias]?.[provider];
+  if (fromDiscovery) return fromDiscovery;
+
   const fallback = defaults.backends?.[backend]?.models?.[alias]?.[provider];
-  if (fallback) return fallback;
+  if (fallback) {
+    if (discovered && !validateModel(fallback, backend, discovered)) {
+      log.warn(`model "${fallback}" (${alias}/${backend}/${provider}) not found in discovered models — using backend default`);
+      const def = discovered.get(backend)?.models?.find(function isDefault(m) { return m.marker === 'default'; });
+      if (def) return def.id;
+    }
+    return fallback;
+  }
 
   // Pass-through for exact model strings
   return alias;

package/packages/classify/README.md

@@ -0,0 +1,136 @@
+# loreli/classify
+
+Prompt-driven LLM classification. Loads a named Mustache template from disk, renders it with the provided content and variables, sends the result through `backends.oneshot()`, and returns the parsed JSON response. The prompt template defines the response shape — classify is generic plumbing.
+
+## Installation
+
+Part of the Loreli monorepo. Import via the package exports map:
+
+```js
+import { classify } from 'loreli/classify';
+```
+
+## Quick Start
+
+Classification requires a `BackendRegistry` with at least one available LLM backend and a prompt template in `packages/classify/prompts/`:
+
+```js
+import { classify } from 'loreli/classify';
+
+const result = await classify('pane-state', paneOutput, {
+  backends: backendRegistry
+});
+// => { category: 'option_dialog', reasoning: 'Trust dialog detected', confidence: 0.9 }
+```
+
+The first argument is the template name — it resolves to `prompts/<name>.md` inside the package. The second argument is the text to classify. The template defines what categories exist, what JSON shape to return, and how the LLM should reason about the input.
+
+## How It Works
+
+```text
+classify('pane-state', text, opts)
+  │
+  ├─ Load prompts/pane-state.md
+  ├─ Mustache.render(template, { content: text, ...opts.vars })
+  ├─ backends.oneshot(rendered, { model, timeout })
+  └─ Parse JSON from LLM response → return object
+```
+
+1. **Load** — Reads `prompts/<name>.md` from disk.
+2. **Render** — Runs Mustache templating. The content is available as `{{{content}}}` (triple-stache, unescaped). Extra variables via `opts.vars` are also available.
+3. **Send** — Calls `backends.oneshot()` with the rendered prompt.
+4. **Parse** — Extracts the first `{...}` JSON object from the response, handling markdown fences and preamble text.
+
+## Prompt Templates
+
+Templates are Markdown files in `packages/classify/prompts/`. Each template contains the full classification instructions for the LLM, including category definitions and the expected JSON output shape.
+
+### `pane-state.md` — orchestrator stall detection
+
+Used by the orchestrator's monitor loop and rapid-death detector to diagnose agent state. Returns `{category, reasoning, confidence}` with states: `working`, `waiting_for_input`, `option_dialog`, `error_loop`, `idle`, `fatal`, `dead`. The `dead` state identifies agents whose process exited or crashed — the orchestrator uses it in the rapid-death window (first 15s after spawn) to classify *why* an agent died, replacing the old binary alive/dead check with diagnostic context.
+
+### `feedback.md` — knowledge feedback categorization
+
+Used by `loreli/knowledge` to classify review feedback. Returns `{category, reasoning, confidence}` with categories: `naming`, `architecture`, `testing`, `documentation`, `performance`, `security`.
+
+### `blocker.md` — knowledge per-ref blocker detection
+
+Used by `loreli/knowledge` to classify issue/PR references as blockers or informational. Receives `{{{content}}}` (joined discussion text) and `{{refs}}` (formatted ref list). Returns `{blockers: [number], references: [number]}`.
+
+### Writing a new template
+
+Create a new `.md` file in `prompts/`. Use `{{{content}}}` for the text to classify (triple-stache prevents HTML escaping). Use `{{varName}}` for additional variables passed via `opts.vars`. End the template with the expected JSON shape so the LLM knows what to return.
+
+The following example shows how a severity template might look:
+
+```markdown
+Classify this error message by severity.
+
+Levels:
+- critical: System is down or data loss is occurring
+- warning: Something is wrong but the system is functional
+- info: Normal operational message
+
+Respond with ONLY a JSON object.
+{"level": "<severity>", "reasoning": "<one sentence>"}
+
+{{{content}}}
+```
+
+Then call it:
+
+```js
+const result = await classify('severity', errorMessage, { backends });
+// => { level: 'critical', reasoning: 'Database connection lost' }
+```
+
+## API Reference
+
+### `classify(name, content, opts)`
+
+Run a named classification prompt against content via LLM.
+
+**Parameters:**
+
+| Name | Type | Default | Description |
+|------|------|---------|-------------|
+| `name` | `string` | — | Template name — resolves to `prompts/<name>.md`. |
+| `content` | `string` | — | Text to classify — injected as `{{{content}}}`. |
+| `opts.backends` | `BackendRegistry` | — | **Required.** Backend registry with `oneshot()` method. |
+| `opts.config` | `Config` | `undefined` | Config instance for model/timeout resolution. |
+| `opts.model` | `string` | `'fast'` | Model alias override. Falls back to `config.classify.model`, then `'fast'`. |
+| `opts.timeout` | `number` | `30000` | Timeout in ms. Falls back to `config.classify.timeout`, then `30000`. |
+| `opts.vars` | `object` | `{}` | Extra Mustache variables beyond `content`. |
+
+**Returns:** `Promise<object>` — Parsed JSON from the LLM. Shape is defined by the prompt template, not enforced by classify.
+
+**Throws:**
+
+| Error | Cause |
+|-------|-------|
+| `classify() requires a backends instance` | `opts.backends` is missing or falsy. |
+| `ENOENT` | Template file `prompts/<name>.md` does not exist. |
+| LLM error (propagated) | `backends.oneshot()` threw (timeout, network, etc.). |
+| `classify: LLM response contains no JSON object` | Response had no `{...}` block. |
+| `classify: failed to parse JSON from LLM response` | Found `{...}` but it was not valid JSON. |
+
+## Configuration
+
+The classify package reads configuration from the `classify` section in `loreli.yml`:
+
+```yaml
+classify:
+  model: fast         # Model alias — resolves via backends
+  maxLines: 100       # Lines of pane output to capture (used by orchestrator)
+  timeout: 30s        # Timeout for the oneshot CLI call
+  maxRetries: 5       # Consecutive failures before safety-net kill
+```
+
+## Error Reference
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `classify() requires a backends instance` | No `backends` option provided. | Pass a `BackendRegistry` instance in `opts.backends`. |
+| Template `ENOENT` | Named template does not exist in `prompts/`. | Create the template file or check the name for typos. |
+| `LLM response contains no JSON object` | The LLM returned prose without any JSON. | Check the template instructions — they should explicitly ask for JSON-only output. |
+| `failed to parse JSON from LLM response` | JSON was found but was malformed. | Usually a transient LLM issue. Retry or use a more capable model. |

package/packages/classify/prompts/blocker.md

@@ -0,0 +1,12 @@
+Analyze this discussion text and classify each referenced issue/PR number as either a blocking dependency or an informational reference.
+
+Referenced issues: {{refs}}
+
+A reference is a **blocker** if the text indicates it must be resolved, merged, or closed before this work can proceed (e.g., "blocked by", "depends on", "needs #N merged first", "waiting for #N").
+
+A reference is **informational** if it is mentioned for context, background, or related reading (e.g., "see #N for context", "related to #N", "similar to #N").
+
+Respond with ONLY a JSON object. Do not wrap in markdown. Do not add any other text.
+{"blockers": [<number>, ...], "references": [<number>, ...]}
+
+{{{content}}}