loreli 0.0.0 → 2.0.0

package/packages/knowledge/README.md

@@ -0,0 +1,217 @@
+# loreli/knowledge
+
+Knowledge capture engine — the write path. Classifies review and plan feedback via LLM, detects recurring patterns across PRs and discussions, and formats patterns into planning objectives for downstream tools.
+
+## Overview
+
+The knowledge package closes the feedback loop in Loreli's agentic workflow. Review comments and plan verdict feedback are classified into categories via LLM, aggregated across PRs and discussions, and when recurring patterns emerge, converted to objectives via `objective()` and routed through `planner.plan()`.
+
+```text
+classify → patterns → objective → planner.plan()
+```
+
+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.
+
+All classification is LLM-powered via `loreli/classify`. Both `classify()` and `classifyRefs()` delegate to on-disk prompt templates — there are no regex heuristics or keyword fallbacks.
+
+## API Reference
+
+### `classify(feedback, opts)`
+
+Categorize feedback text into a category via LLM. Delegates to `loreli/classify` using the `feedback` prompt template, which defines six categories: naming, architecture, testing, documentation, performance, security.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `feedback` | `string` | Review or verdict comment text. |
+| `opts.backends` | `BackendRegistry` | **Required.** Backend registry for LLM classification. |
+| `opts.config` | `Config` | Config instance for model/timeout resolution. |
+
+**Returns:** `Promise<{ category: string, confidence: number }>`
+
+- `category` — One of: `naming`, `architecture`, `testing`, `documentation`, `performance`, `security`.
+- `confidence` — `0.0` to `1.0` as returned by the LLM. Defaults to `0.8` when the LLM omits it.
+
+**Throws:** When `backends` is missing or the LLM call fails. Callers must wrap in `try/catch`.
+
+The following example classifies a review comment about naming conventions:
+
+```js
+import { classify } from 'loreli/knowledge';
+
+const { category, confidence } = await classify(
+  'The naming convention should follow camelCase for consistency',
+  { backends: backendRegistry }
+);
+// category: 'naming', confidence: 0.85
+```
+
+### `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, opts)`
+
+Classify extracted references as blockers or informational via LLM. Delegates to `loreli/classify` using the `blocker` prompt template, which performs per-reference classification — each ref is individually classified as either a blocking dependency or an informational reference.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `comments` | `Array<{ body: string, author?: string }>` | Discussion comments containing the refs. |
+| `refs` | `number[]` | Extracted reference numbers from `extractRefs()`. |
+| `opts.backends` | `BackendRegistry` | **Required.** Backend registry for LLM classification. |
+| `opts.config` | `Config` | Config instance for model/timeout resolution. |
+
+**Returns:** `Promise<{ blockers: number[], references: number[] }>`
+
+Returns immediately with empty arrays when `refs` is empty (no LLM call made).
+
+**Throws:** When `backends` is missing or the LLM call fails. Callers must wrap in `try/catch`.
+
+The following example classifies references from a plan discussion where `#5` is a blocker and `#6` is informational:
+
+```js
+import { classifyRefs, extractRefs } from 'loreli/knowledge';
+
+const comments = [
+  { body: 'Blocked by #5', author: 'reviewer' },
+  { body: 'See #6 for context', author: 'reviewer' }
+];
+const refs = extractRefs(comments);
+const result = await classifyRefs(comments, refs, { backends: backendRegistry });
+// { blockers: [5], references: [6] }
+```
+
+### `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.
+
+### `objective(pattern)`
+
+Formats a detected feedback pattern into a planning objective string. Embeds a `loreli:feedback` marker so downstream tools can auto-detect the feedback category.
+
+**Parameters:**
+
+| Name | Type | Description |
+|------|------|-------------|
+| `pattern` | `object` | Pattern object from `patterns()` with `category`, `count`, `refs` fields. |
+
+**Returns:** `string` — Multi-line string containing the marker, a description of what to update, refs, and suggested target file.
+
+The following example detects patterns, formats each as an objective, and passes it to the planner:
+
+```js
+import { patterns, objective } from 'loreli/knowledge';
+
+const found = await patterns(hub, repo, { threshold: 5 });
+for (const pattern of found) {
+  const text = objective(pattern);
+  await planner.plan(repo, text, { feedbackCategory: pattern.category });
+}
+```
+
+## 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). |
+
+## 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()`). Pattern detection 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. Cross-provider consensus (multiple LLM providers flagging the same category) lowers the effective threshold by 1.
+
+**`categories`** — The six categories that `classify()` can return. These are defined in the `feedback.md` prompt template in `loreli/classify`:
+
+| Category | What it captures |
+|----------|------------------|
+| `naming` | Naming convention violations and style inconsistencies |
+| `architecture` | Structural concerns, module boundaries, coupling issues |
+| `testing` | Missing tests, inadequate coverage, testing methodology |
+| `documentation` | Missing or incomplete documentation |
+| `performance` | Performance issues, optimization opportunities |
+| `security` | Security vulnerabilities, credential exposure, auth issues |
+
+To modify categories, edit the `feedback.md` prompt template in `packages/classify/prompts/`.
+
+## Errors
+
+| Error | Cause | Resolution |
+|-------|-------|------------|
+| `classify() requires a backends instance` | No `backends` option provided to `classify()` or `classifyRefs()`. | Pass a `BackendRegistry` instance from the orchestrator. |
+| LLM timeout / network error | The `oneshot()` call failed. | Check backend availability. Callers should wrap in `try/catch` and degrade gracefully. |
+| `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,243 @@
+/**
+ * Knowledge capture engine — the write path.
+ *
+ * Classifies review feedback via LLM, 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 { classify as llmClassify } from 'loreli/classify';
+import { logger } from 'loreli/log';
+import { createHash } from 'node:crypto';
+
+const log = logger('knowledge');
+
+/**
+ * Classify review feedback text into a category via LLM.
+ *
+ * Delegates to `loreli/classify` using the `feedback` prompt template.
+ * The prompt defines six categories: naming, architecture, testing,
+ * documentation, performance, security.
+ *
+ * @param {string} feedback - Review comment text.
+ * @param {object} [opts] - Options.
+ * @param {object} opts.backends - BackendRegistry instance. Required.
+ * @param {object} [opts.config] - Config instance for model/timeout resolution.
+ * @returns {Promise<{category: string, confidence: number}>}
+ */
+export async function classify(feedback, opts = {}) {
+  const result = await llmClassify('feedback', feedback, {
+    backends: opts.backends,
+    config: opts.config
+  });
+  return { category: result.category, confidence: result.confidence ?? 0.8 };
+}
+
+/**
+ * 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),
+      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 file paths for objective() output.
+ *
+ * @type {Record<string, string>}
+ */
+const OBJECTIVE_FILES = {
+  agents: 'AGENTS.md',
+  planner: '.loreli/planner.md',
+  reviewer: '.loreli/review.md',
+  action: '.loreli/action.md',
+  risk: '.loreli/risk.md'
+};
+
+/**
+ * Format a detected feedback pattern into a planning objective string.
+ *
+ * Embeds a `loreli:feedback` marker so downstream tools can auto-detect
+ * the feedback category and apply appropriate labels.
+ *
+ * @param {object} pattern - Pattern from patterns().
+ * @returns {string} Planning objective text.
+ */
+export function objective(pattern) {
+  const suggested = target(pattern.refs);
+  const file = OBJECTIVE_FILES[suggested] ?? 'AGENTS.md';
+  const refs = pattern.refs
+    .slice(0, 10)
+    .map(function fmt(r) {
+      const prefix = r.type === 'discussion' ? 'Discussion' : 'PR';
+      return `- ${prefix} #${r.ref}: "${r.excerpt}"`;
+    })
+    .join('\n');
+
+  return [
+    mark('feedback', { category: pattern.category }),
+    '',
+    `Update \`${file}\` to enforce a new standard for "${pattern.category}"`,
+    'based on recurring review feedback.',
+    '',
+    `This pattern appeared ${pattern.count} times:`,
+    refs,
+    '',
+    `Category: ${pattern.category}`,
+    `Suggested target: ${file}`
+  ].join('\n');
+}
+
+/**
+ * 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 via LLM.
+ *
+ * Delegates to `loreli/classify` using the `blocker` prompt template,
+ * which returns per-ref classification: `{blockers: [...], references: [...]}`.
+ *
+ * @param {Array<{body: string, author?: string}>} comments - Discussion comments containing the refs.
+ * @param {number[]} refs - Extracted reference numbers.
+ * @param {object} [opts] - Options.
+ * @param {object} opts.backends - BackendRegistry instance. Required.
+ * @param {object} [opts.config] - Config instance.
+ * @returns {Promise<{blockers: number[], references: number[]}>}
+ */
+export async function classifyRefs(comments, refs, opts = {}) {
+  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 result = await llmClassify('blocker', text, {
+    backends: opts.backends,
+    config: opts.config,
+    vars: { refs: refs.map(function fmt(r) { return '#' + r; }).join(', ') }
+  });
+
+  return {
+    blockers: result.blockers ?? [],
+    references: result.references ?? []
+  };
+}

package/packages/log/README.md

@@ -0,0 +1,93 @@
+# loreli/log
+
+Structured, session-aware logging for all Loreli packages. Writes to both console and `~/.loreli/` log files with per-agent log separation.
+
+## API Reference
+
+### `logger(pkg)` → Logger
+
+Create or retrieve a logger scoped to a package name. Every entry is tagged with `{ package: pkg }`.
+
+```js
+import { logger } from 'loreli/log';
+
+const log = logger('agent');
+log.info('claimed issue', { issue: 42 });
+log.warn('rate limit approaching', { remaining: 50 });
+log.error('spawn failed', { error: 'binary not found' });
+log.debug('tmux capture', { paneId: '%3' });
+```
+
+### `logger(pkg).agent(name)` → Logger
+
+Create a per-agent sub-logger. Writes to a dedicated `<name>.log` file and tags every entry with `{ agent: name }`.
+
+```js
+const log = logger('agent');
+const agentLog = log.agent('optimus-0');
+agentLog.info('PR created', { pr: 17 });
+// -> writes to ~/.loreli/sessions/<id>/logs/optimus-0.log
+```
+
+### `bind(opts)`
+
+Bind the logging subsystem to a session. After binding, all loggers gain a file transport.
+
+| Option | Type | Description |
+|--------|------|-------------|
+| `session` | `string` | Session ID — logs write to `~/.loreli/sessions/<session>/logs/` |
+| `home` | `string` | Override the base directory (default: `~/.loreli/`) |
+
+```js
+import { bind } from 'loreli/log';
+bind({ session: 'a1b2c3d4', home: process.env.LORELI_HOME });
+```
+
+When only `home` is provided (no session), logs write to `<home>/loreli.log` as a pre-session fallback.
+
+### `reset()`
+
+Clear all cached loggers and state. Used in tests to ensure isolation between runs.
+
+## Log File Layout
+
+```
+~/.loreli/
+  loreli.log                             (pre-session fallback)
+  sessions/
+    a1b2c3d4/
+      logs/
+        orchestrator.log                 (server-level events)
+        optimus-0.log                    (per-agent log)
+        megatron-0.log
+```
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `LORELI_LOG_LEVEL` | `info` | Console log level (`error`, `warn`, `info`, `debug`) |
+| `LORELI_HOME` | `~/.loreli/` | Base directory for log files |
+
+File transport always writes at `debug` level in JSON format for post-mortem analysis. Console transport respects `LORELI_LOG_LEVEL`.
+
+### Configuration via loreli/config
+
+When used through Loreli's orchestration layer, logging settings are configurable via `loreli.yml`:
+
+| Config Key | Default | Description |
+|------------|---------|-------------|
+| `log.level` | `info` | Console log level |
+| `log.maxSize` | `10485760` | Max size per log file in bytes (10 MB) |
+| `log.maxFiles` | `3` | Number of rotated log files to keep |
+
+The `LORELI_LOG_LEVEL` environment variable still works and is resolved as an environment layer in config's resolution chain (between `loreli.yml` and built-in defaults).
+
+## Design Decisions
+
+- **Lazy file transport**: File transport is only added after `bind()`. Before that, only console is active.
+- **Per-agent isolation**: Each agent gets its own log file for easy debugging.
+- **Size-based rotation**: 10MB per file, 3 rotated files kept.
+- **JSON file format**: Machine-parseable for CI/monitoring. Console uses human-readable format.