loreli 0.0.0 → 2.0.0

package/packages/config/README.md

@@ -0,0 +1,898 @@
+# loreli/config
+
+Centralized configuration for Loreli. Reads `loreli.yml` from target repositories, merges with start parameters and environment variables, and provides typed defaults for every configurable value in the system.
+
+## How It Works
+
+```mermaid
+flowchart TD
+  BP["Start Params"] --> Merge["Config.merge()"]
+  YML["loreli.yml (repo)"] --> Load["Config.load()"]
+  Load --> Resolve["Config.get(path)"]
+  Merge --> Resolve
+  DOT[".env file"] --> LoadEnv["loadEnv()"]
+  LoadEnv --> PEnv["process.env"]
+  PEnv --> Resolve
+  DEF["Built-in Defaults"] --> Resolve
+  Resolve --> Value["Resolved Value"]
+```
+
+Config values are resolved through four layers, highest priority first:
+
+1. **Start tool params** -- explicit per-invocation overrides via `config.merge()`
+2. **`loreli.yml`** -- repo-level config read via `hub.read()` during `config.load()`
+3. **Environment variables** -- shell env and `.env` file (via `loadEnv()`)
+4. **Built-in defaults** -- hardcoded in `defaults.js`
+
+## API Reference
+
+### `new Config()`
+
+Creates a config instance with empty layers. All `get()` calls return built-in defaults until `load()` or `merge()` is called.
+
+### `config.load(hub, repo)` -> `Promise<boolean>`
+
+Read `loreli.yml` from the target repo root via `hub.read()`. Returns `true` if the file was found, `false` otherwise. When the file is missing, defaults apply gracefully.
+
+The following example demonstrates loading config from a repo, which is the first step in start:
+
+```js
+import { Config } from 'loreli/config';
+
+const config = new Config();
+const found = await config.load(hub, 'owner/repo');
+// found === true if loreli.yml exists
+```
+
+### `config.loadLocal(path?)` -> `boolean`
+
+Read local `loreli.yml` from disk (default `./loreli.yml`) using the same parser and schema validation as `load()`. Returns `true` when the file exists and parses, `false` otherwise.
+
+The following example demonstrates loading config in standalone CLI contexts where no Hub instance is available yet:
+
+```js
+import { Config } from 'loreli/config';
+
+const config = new Config();
+const found = config.loadLocal('loreli.yml');
+// found === true when local loreli.yml exists
+```
+
+### `config.merge(overrides)`
+
+Apply a plain object on top of all other layers. Nested objects are shallow-merged one level deep. Values are validated through the schema -- invalid types are silently discarded.
+
+The following example shows how start params override file-level config:
+
+```js
+config.merge({ theme: 'pokemon', reviewers: ['alice'] });
+config.get('theme'); // 'pokemon' (overridden)
+```
+
+### `config.get(path)` -> `*`
+
+Resolve a config value through all layers using dot-notation. Returns `undefined` for completely unknown paths.
+
+The following example demonstrates accessing nested and top-level values:
+
+```js
+config.get('theme');           // 'transformers'
+config.get('repo');            // 'owner/repo' (when configured)
+config.get('merge.method');    // 'squash'
+config.get('timeouts.stall');  // 600000
+config.get('reviewers');       // []
+```
+
+### `config.toJSON()` -> `object`
+
+Serialize the fully resolved config to a plain object, walking every default key and resolving each through the layer chain. Used for session persistence.
+
+### `config.found` -> `boolean`
+
+Whether `loreli.yml` was found during the last `load()` call. Used by start to decide if the file needs scaffolding.
+
+### `loadEnv(path?)` -> `boolean`
+
+Load a `.env` file into `process.env` using Node's built-in `process.loadEnvFile()`. Variables already present in the shell environment are **not** overwritten, so shell exports always win.
+
+Returns `true` if the file was loaded, `false` if it does not exist. Any other I/O error is re-thrown.
+
+The following example demonstrates loading a `.env` file before creating a `Config` instance, which is the recommended pattern for local development and testing. The loaded variables flow into `Config.get()` through the existing env layer — no extra wiring needed:
+
+```js
+import { loadEnv, Config } from 'loreli/config';
+
+loadEnv();                       // loads .env from cwd (silent no-op if missing)
+const config = new Config();
+config.get('github.token');      // resolves GITHUB_TOKEN from .env
+config.get('log.level');         // resolves LORELI_LOG_LEVEL from .env
+```
+
+The following example shows loading from an explicit path, which is useful in tests or CI where the `.env` file lives in a non-standard location:
+
+```js
+import { loadEnv } from 'loreli/config';
+
+const found = loadEnv('/path/to/project/.env.test');
+// found === true if the file existed
+```
+
+> **Note:** `loadEnv` uses Node's built-in `process.loadEnvFile()` (available since Node 20.12). No external dependencies are required. The project targets Node >= 24.
+
+## `loreli.yml` Schema
+
+This file lives in the **target repository** root (the repo agents work on). It is scaffolded by start if absent.
+
+```yaml
+# loreli.yml - repo-level orchestration config
+# See https://www.npmjs.com/package/loreli for full documentation.
+#
+# Duration fields support both numbers (milliseconds) and strings parsed by `ms`.
+# Prefer strings like 10m, 1h, 3d for readability.
+
+# --- Identity ---
+# theme
+# What: Chooses naming/theme vocabulary for agent identities and system messages.
+# Impact: Cosmetic only; does not change orchestration behavior or model quality.
+# Signal: Humans find agent identity/readability poor in PRs, comments, or dashboards.
+# Change when: You want agent names/messages to match your team's preferred style.
+theme: transformers          # string or list: transformers | pokemon | marvel | digimon | starwars | lotr | dragonball | avatar | zelda
+# theme:                     # list = randomize theme per work item
+#   - transformers
+#   - pokemon
+#   - marvel
+
+# --- Agent defaults ---
+# model
+# What: Default model tier when tools do not specify a model explicitly.
+# Impact: Higher tiers are usually stronger but slower/more expensive.
+# Signal: Repeated low-quality outputs at current tier, or cost/latency pressure from higher tiers.
+# Change when: You want a global quality/cost baseline shift for all agents.
+model: balanced              # fast | balanced | powerful | exact model string
+
+# repo
+# What: Optional repository slug fallback for standalone tool contexts before start runs.
+# Impact: Enables tools like `loreli tools context`, `start_work`, and `hitl` to resolve repository scope without session hydration.
+# Signal: CLI tools report "No repository configured" outside agent/start sessions.
+# Change when: You regularly run Loreli tools directly from a shell and want a persistent repo default.
+# repo: owner/repo
+
+# --- Merge gate ---
+# reviewers
+# What: GitHub usernames for HITL review requests.
+# Impact: Non-empty reviewers typically means more human approval steps.
+# Signal: PRs merge without enough human oversight, or reviewer assignment is missing expected owners.
+# Change when: You want specific humans looped into merges.
+reviewers: []                # empty = autonomous merge path
+
+merge:
+  # merge.method
+  # What: Git merge strategy used by Loreli when merging approved PRs.
+  # Impact: Changes commit history shape (single squash commit vs merge commit vs rebase history).
+  # Signal: Repository policy violations or maintainer feedback about history shape.
+  # Change when: Your repo has a strict merge policy.
+  method: squash             # squash | merge | rebase
+
+  # merge.hitl
+  # What: Enables/disables Human In The Loop merge gating.
+  # Impact: true blocks final merge on human approval; false allows full automation.
+  # Signal: Unexpected autonomous merges (need true) or merge throughput too slow due to manual gates (consider false).
+  # Change when: You need more safety (set true) or more autonomy/speed (set false).
+  hitl: false
+
+  # merge.base
+  # What: Base branch target for agent PRs.
+  # Impact: Controls where agent changes accumulate (for example staging branch vs main).
+  # Signal: Main branch receiving agent merges too early, or release managers asking for a promotion/staging lane.
+  # Change when: You want agents to merge into an integration branch before promotion to main.
+  base: loreli
+
+# --- PR quality gates ---
+pr:
+  validation:
+    # pr.validation.command
+    # What: Shell command run before `pr/create` is allowed.
+    # Impact: Non-zero exit blocks PR creation; stronger checks reduce bad PRs but increase latency.
+    # Signal: PRs repeatedly fail CI after creation (tighten command), or PR creation is bottlenecked by long prechecks (lighten command).
+    # Change when: You want a different gate (for example lint+test, unit-only, or build-only).
+    command: npm test
+
+  selfReview:
+    # pr.selfReview.enabled
+    # What: Requires a preview step before actual PR creation.
+    # Impact: Adds one extra tool step but catches obvious metadata/diff mistakes early.
+    # Signal: Frequent wrong-base/wrong-scope PRs (enable), or operators report friction from two-step create flow (disable).
+    # Change when: You want faster single-step PR creation (set false) or stricter guardrails (true).
+    enabled: true
+
+# --- HITL behavior ---
+hitl:
+  # hitl.timeout
+  # What: Max idle age for HITL-owned claims before stale-claim eviction logic can act.
+  # Impact: Lower values recycle stuck ownership faster; higher values preserve ownership longer.
+  # Signal: Claims remain stuck for days (decrease), or valid long human review cycles get evicted too early (increase).
+  # Change when: Human review cadence is slower/faster than current default.
+  # Special: null disables stale-claim eviction in HITL mode.
+  timeout: 3d
+
+# --- Stall and lifecycle timeouts ---
+timeouts:
+  # timeouts.stall
+  # What: No-activity threshold for stall escalation.
+  # Impact: >stall triggers tier-1, >2x triggers tier-2 warning, >3x triggers kill.
+  # Signal: Agents killed during legitimate long runs (increase), or stalled agents consume slots too long (decrease).
+  # Change when: Agents are killed too aggressively on long tasks (increase),
+  #              or stuck agents linger too long (decrease).
+  stall: 10m
+
+  # timeouts.shutdown
+  # What: Grace window for cooperative shutdown before force stop.
+  # Impact: Lower values free resources faster; higher values allow cleaner agent exits.
+  # Signal: Frequent force-kill shutdowns while agents are still finishing final output (increase),
+  #         or shutdown hangs tying up capacity (decrease).
+  # Change when: Agents need more time to finalize output before shutdown.
+  shutdown: 1m
+
+  # timeouts.poll
+  # What: Poll cadence during shutdown waiting loop.
+  # Impact: Lower values detect stop faster but increase loop overhead.
+  # Signal: Slow recognition of completed shutdowns (decrease), or excessive polling/log churn during shutdown (increase).
+  # Change when: You want quicker shutdown detection or lower polling churn.
+  poll: 2s
+
+  # timeouts.rapidDeath
+  # What: Startup watch window used to detect immediate backend failures.
+  # Impact: Helps mark unhealthy backends degraded sooner after repeated instant failures.
+  # Signal: Backends crash quickly but are not degraded soon enough (increase), or degraded too aggressively from transient startup blips (decrease).
+  # Change when: Startup failures are missed (increase) or false positives occur (decrease).
+  rapidDeath: 15s
+
+  # timeouts.proxyDiscovery
+  # What: HTTP timeout for proxy model discovery calls used by claude/codex.
+  # Impact: Lower values fail fast on unhealthy proxies; higher values tolerate slower proxy endpoints.
+  # Signal: Discovery often logs timeout failures on healthy but slow networks (increase),
+  #         or startup blocks too long on dead proxy endpoints (decrease).
+  # Change when: Proxy-backed environments need slower/faster discovery behavior.
+  proxyDiscovery: 5s
+
+  # timeouts.nudge
+  # What: Enables/disables tier-1 "you appear stalled" message.
+  # Impact: true may interrupt deep work; false keeps escalation signals without message interruption.
+  # Signal: Agents frequently context-switch into status reporting mid-task (disable), or teams need explicit stall prompts (enable).
+  # Change when: Long-running autonomous tasks should not be interrupted.
+  nudge: true
+
+# --- Reactor polling ---
+watch:
+  # watch.interval
+  # What: Main orchestration tick interval.
+  # Impact: Lower = faster reaction to new issues/PR state changes, higher API/process load.
+  # Signal: Claim/review actions happen too slowly after repo events (decrease), or API rate pressure/churn is high (increase).
+  # Change when: You need faster responsiveness or lower background churn.
+  interval: 1m
+
+  # watch.maxRounds
+  # What: Maximum re-review/rework loop cycles before escalation.
+  # Impact: Higher values allow deeper autonomous iteration; lower values force earlier human escalation.
+  # Signal: PRs escalate before they can converge autonomously (increase), or loops churn too long without convergence (decrease).
+  # Change when: PRs routinely need more/less autonomous correction rounds.
+  maxRounds: 7
+
+  # watch.maxClaims
+  # What: Max simultaneous issue claims per action agent.
+  # Impact: Higher increases per-agent throughput but can dilute focus and increase context switching.
+  # Signal: Idle action agents with unclaimed work (increase), or agents juggle too many tasks and miss follow-through (decrease).
+  # Change when: Agents are underutilized (increase) or overloaded (decrease).
+  maxClaims: 3
+
+# --- Workflow policy (per-role) ---
+# workflows.{role}
+# What: Per-role model, scaling, trace, prompt, and risk-skip overrides.
+# Impact: Fine-grained control over each workflow without global changes.
+# Signal: One role needs different model/scaling/trace than others.
+# Change when: You want role-specific tuning.
+# Resolution: workflows.{role}.model → global model → 'balanced'
+# Each role may also set: prompt (file path), trace.{enabled,maxOutputChars}
+# Risk additionally supports: skip (skips mandatory risk verdict checks)
+workflows:
+  action:
+    model: balanced
+    maxAgents: 3
+  reviewer:
+    model: balanced
+    maxAgents: 2
+    trace:
+      enabled: true
+      maxOutputChars: 4000
+  risk:
+    model: fast
+    maxAgents: 3
+    skip: false
+    trace:
+      enabled: true
+      maxOutputChars: 2000
+  planner:
+    model: powerful
+    maxAgents: 1
+    trace:
+      enabled: true
+      maxOutputChars: 4000
+
+# --- Scaling policy (global) ---
+scaling:
+  # scaling.maxAgents
+  # What: Global cap for active non-dormant agents.
+  # Impact: Upper bound on parallelism and compute/resource consumption.
+  # Signal: Backlog grows with idle infrastructure (increase), or host/API limits are saturated (decrease).
+  # Change when: You need more throughput (increase) or tighter resource limits (decrease).
+  maxAgents: 8
+
+  # scaling.maxPerTick
+  # What: Spawn budget per reactor tick.
+  # Impact: Higher values ramp up faster but can spike load.
+  # Signal: Slow recovery from empty capacity (increase), or sudden spawn bursts causing instability (decrease).
+  # Change when: Startup/recovery is too slow (increase) or too bursty (decrease).
+  maxPerTick: 2
+
+  # scaling.cooldown
+  # What: Minimum delay before spawning another agent of the same role.
+  # Impact: Prevents spawn thrashing when demand oscillates.
+  # Signal: Repeated rapid spawn/stop cycles for same role (increase), or role fill speed too slow during sustained demand (decrease).
+  # Change when: You see role churn/flapping or need faster re-scaling.
+  cooldown: 30s
+
+# --- Logging ---
+log:
+  # log.level
+  # What: Minimum severity written to logs.
+  # Impact: Lower levels (debug/trace) increase observability and log volume.
+  # Signal: Hard-to-diagnose behavior with insufficient log detail (lower level), or noisy oversized logs (raise level).
+  # Change when: Debugging production behavior or reducing noise.
+  level: info                # error | warn | info | debug | trace
+
+  # log.maxSize
+  # What: Per-file rotation size threshold in bytes.
+  # Impact: Larger files reduce rotation frequency but grow disk usage per file.
+  # Signal: Too-frequent rotations splitting incidents (increase), or very large log files hard to handle (decrease).
+  # Change when: You want fewer rotations or smaller log files.
+  maxSize: 10485760          # 10 MB
+
+  # log.maxFiles
+  # What: Number of rotated files retained.
+  # Impact: Higher values keep more history and consume more disk.
+  # Signal: Needed historical context disappears before investigation (increase), or disk pressure from logs (decrease).
+  # Change when: You need longer local forensic history.
+  maxFiles: 3
+
+# --- Labels ---
+labels:
+  # labels.track
+  # What: Adds Loreli/provider/model tracking labels to issues and PRs.
+  # Impact: Better observability/filtering in GitHub labels, but more label traffic.
+  # Signal: Need to filter/report by provider/role/model (enable), or label clutter complaints from maintainers (disable).
+  # Change when: You want a cleaner label surface (set false).
+  track: true
+
+  # labels.extra
+  # What: Extra labels applied to all Loreli-created items.
+  # Impact: Improves triage/routing automation via label-based workflows.
+  # Signal: Manual relabeling happens repeatedly after Loreli creates items.
+  # Change when: You need team/project labels attached automatically.
+  extra: []
+
+# --- Agent tool restrictions ---
+agents:
+  disallowedTools:
+    # agents.disallowedTools
+    # What: Commands agents cannot execute directly.
+    # Impact: Helps prevent bypassing MCP guardrails and policy checks.
+    # Signal: Agents attempt raw GitHub/API shell tooling that bypasses Loreli controls.
+    # Change when: You need stricter/looser command policy.
+    - gh
+    - curl
+
+# --- Backend model/env overrides ---
+# backends.{name}.models
+# What: Per-backend tier/provider model routing overrides.
+# Impact: Changes model selection without code changes — overrides both
+#         runtime discovery and static defaults. Required for LiteLLM/proxy setups.
+# Signal: Specific backend underperforms at current tier/provider mapping,
+#         or you're behind a proxy that uses different model names.
+# Change when: You need backend-specific model tuning or custom proxy routing.
+# Resolution: config override > runtime discovery > static defaults > pass-through
+# Note: When cursor-agent is available, models are auto-discovered at startup
+#       via `--list-models`. Config overrides always take precedence over discovery.
+#
+# backends.{name}.env
+# What: Env vars injected into backend launcher scripts.
+# Impact: Controls API base URLs, auth endpoints, and backend runtime options.
+# Signal: Backend needs proxy routing/custom endpoint/auth flag and current environment inheritance is insufficient.
+# Change when: You use proxies/self-hosted gateways/custom backend flags.
+#
+# backends:
+#   claude:
+#     env:
+#       ANTHROPIC_BASE_URL: https://your-proxy.example.com/v1
+#     models:
+#       fast:
+#         anthropic: claude-haiku-4-5-20251001
+#       balanced:
+#         anthropic: claude-sonnet-4-5-20250929
+#       powerful:
+#         anthropic: claude-opus-4-5-20251101
+#   codex:
+#     env:
+#       OPENAI_BASE_URL: https://your-proxy.example.com/v1
+#     models:
+#       fast:
+#         openai: gpt-5-mini
+#       balanced:
+#         openai: gpt-5.1-codex
+#       powerful:
+#         openai: gpt-5.2-pro
+#   cursor:
+#     models:
+#       fast:
+#         anthropic: sonnet-4.5
+#         openai: gpt-5.3-codex-low
+#       balanced:
+#         anthropic: sonnet-4.5-thinking
+#         openai: gpt-5.3-codex
+#       powerful:
+#         anthropic: opus-4.6-thinking
+#         openai: gpt-5.1-codex-max
+
+# --- Trace capture (global defaults) ---
+# Per-role trace overrides live under workflows.{role}.trace
+trace:
+  # trace.enabled
+  # What: Master switch for workflow trace collection.
+  # Impact: Off reduces trace artifacts; on improves debuggability.
+  # Signal: Missing forensic context during incidents (enable), or trace storage overhead too high (disable).
+  # Change when: You need to reduce trace volume or increase diagnostics.
+  enabled: true
+
+  # trace.includeOutput
+  # What: Include model/tool output snippets in traces.
+  # Impact: Better debugging context but larger logs and potentially sensitive output in traces.
+  # Signal: Investigations lack enough output context (enable), or traces include too much sensitive/noisy content (disable).
+  # Change when: You want minimal traces or stricter output hygiene.
+  includeOutput: true
+
+  # trace.maxOutputChars
+  # What: Global cap of captured output chars per trace item.
+  # Impact: Higher captures richer context but grows trace size.
+  # Signal: Trace snippets are cut before key error details appear (increase), or traces are too large/noisy (decrease).
+  # Change when: Useful context is being truncated too aggressively.
+  maxOutputChars: 8000
+
+# --- Proof of life ---
+proofOfLife:
+  # proofOfLife.timeout
+  # What: Wait window for liveness responses before stale claim eviction actions.
+  # Impact: Lower values reclaim work faster; higher values are more tolerant of slow responses.
+  # Signal: Active claims get evicted while agents are still responsive (increase), or dead claims linger too long (decrease).
+  # Change when: Claims are reclaimed too quickly or too slowly.
+  timeout: 5m
+
+# --- Workspace lifecycle ---
+workspace:
+  # workspace.cleanup
+  # What: Deletes per-agent workspace directories on kill/shutdown.
+  # Impact: true saves disk space; false preserves artifacts for debugging.
+  # Signal: Disk growth from stale workspaces (enable), or need post-run forensic inspection (disable).
+  # Change when: You want cleaner disks (true) or post-mortem inspection (false).
+  cleanup: false
+
+# --- Session cleanup ---
+cleanup:
+  # cleanup.retention
+  # What: Age threshold for pruning old sessions.
+  # Impact: Lower values reduce disk usage; higher values keep history longer.
+  # Signal: Session storage growth pressure (decrease), or historical debugging context disappears too soon (increase).
+  # Change when: You need more/less historical session retention.
+  retention: 12h
+
+  # cleanup.autoprune
+  # What: Runs prune/sweep automatically at start.
+  # Impact: true keeps storage tidy without manual cleanup.
+  # Signal: Accumulated stale files/sessions between runs (enable), or need strict manual lifecycle control (disable).
+  # Change when: You want explicit/manual cleanup control (set false).
+  autoprune: true
+
+# --- Feedback and knowledge capture ---
+feedback:
+  # feedback.enabled
+  # What: Master switch for feedback marker capture and knowledge aggregation.
+  # Impact: false disables automated pattern accumulation.
+  # Signal: Need to temporarily pause all feedback mining/noise.
+  # Change when: You want to pause feedback mining entirely.
+  enabled: true
+
+  # feedback.threshold
+  # What: Repeat-count threshold before a feedback pattern is promoted/escalated.
+  # Impact: Lower values promote patterns sooner; higher values reduce noisy promotions.
+  # Signal: Too many low-signal promotions (increase), or important repeated issues taking too long to surface (decrease).
+  # Change when: Pattern promotion is too noisy (increase) or too slow (decrease).
+  threshold: 5
+
+  # feedback.categories
+  # What: Allowed classifier buckets for captured feedback.
+  # Impact: Removed categories are ignored by pattern promotion.
+  # Signal: Certain feedback classes are irrelevant/noisy for your team.
+  # Change when: You want to focus feedback mining on specific quality dimensions.
+  categories:
+    - naming
+    - architecture
+    - testing
+    - documentation
+    - performance
+    - security
+
+  # feedback.hitl
+  # What: Controls Human In The Loop escalation for feedback-driven PRs at merge time.
+  # Impact: true gates all feedback PRs on human approval; false allows full automation; array gates only listed categories.
+  # Signal: Feedback-driven changes landing without review (set true or list categories), or unnecessary merge friction (set false).
+  # Change when: You want human oversight on specific feedback categories (e.g. architecture, security) while letting others auto-merge.
+  hitl: false
+
+# --- Tmux ---
+tmux:
+  # tmux.session
+  # What: Shared tmux session name where agent panes run.
+  # Impact: Changing this isolates Loreli panes into a different tmux session namespace.
+  # Signal: Multiple orchestrations collide in same tmux namespace.
+  # Change when: Running multiple isolated Loreli orchestrations on one machine.
+  session: loreli
+
+  # tmux.capture
+  # What: Number of pane history lines Loreli reads when inspecting output.
+  # Impact: Higher values improve diagnostics but increase capture overhead.
+  # Signal: Error root cause appears just above currently captured history window.
+  # Change when: Important error context scrolls out of captured history.
+  capture: 500
+
+# --- GitHub auth override ---
+# github.token
+# What: Fallback GitHub token in config (env token is preferred).
+# Impact: Enables Hub API auth when env injection is unavailable.
+# Signal: Hub/API auth failures in environments where you cannot set env vars.
+# Change when: You cannot provide GITHUB_TOKEN via environment.
+# github:
+#   token: ghp_your_token_here
+
+```
+
+## Configurable Base Branch
+
+By default agents create pull requests against `main`. The `merge.base` setting redirects all agent work to a dedicated branch, keeping `main` untouched until a human is ready to promote.
+
+### Why
+
+Agents run autonomously — often overnight or in batch. Pointing them at a dedicated branch (e.g. `loreli`) creates a natural safety boundary: agent-produced PRs merge into `loreli`, and a single human-reviewed PR promotes the batch from `loreli` into `main`. This prevents unreviewed agent code from landing on `main` directly.
+
+### How to Enable
+
+Set `merge.base` in the target repository's `loreli.yml`:
+
+```yaml
+merge:
+  base: loreli
+```
+
+The scaffolding template (`loreli.yml` generated by start) already defaults to `loreli`. Repositories that omit `merge.base` or set it to `main` retain the current behavior — agents PR directly against `main`.
+
+### What It Affects
+
+The setting flows through every system boundary that references a base branch:
+
+| System | Behavior |
+|--------|----------|
+| **Workspace reset** (`reset()`) | Agent workspaces are force-recreated from `origin/<base>` instead of `origin/main` when recycling between issues. The base ref is explicitly fetched since agent clones use `--single-branch`. |
+| **PR creation** (`pr` tool) | PRs opened by action agents target `<base>` instead of `main`. The base is resolved from config and can be overridden per-call via the `base` argument. |
+| **Relay auto-PR** (action workflow) | When the action workflow auto-creates a PR on behalf of a dormant agent, it uses the configured base. |
+| **Review checkout** (`checkout()`) | Reviewer workspaces sync the configured base branch alongside the PR head so diffs are computed against the correct parent. |
+| **Re-review dispatch** (review workflow) | Re-review prompts include the configured base in PR metadata so reviewers evaluate against the correct target. |
+
+### Resolution Order
+
+`merge.base` follows the standard config resolution chain:
+
+1. **Start params** — `config.merge({ merge: { base: 'develop' } })`
+2. **`loreli.yml`** — `merge.base: loreli`
+3. **Built-in default** — `main`
+
+Every call site uses `cfg?.get?.('merge.base') ?? 'main'` as the resolution pattern, ensuring the system degrades gracefully when config is unavailable.
+
+### Workflow
+
+The intended workflow with `merge.base: loreli`:
+
+```
+main ──────────────────────────────────────── human review ──▶ main
+  │                                                  ▲
+  └──▶ loreli ──▶ agent PRs merge here ──────────────┘
+         │            ▲         ▲
+         ├── agent-0/issue-1 ───┘         (auto-merge)
+         └── agent-1/issue-2 ───┘         (auto-merge)
+```
+
+Agents branch from `loreli`, open PRs against `loreli`, and their work is auto-merged (or HITL-reviewed) into `loreli`. A separate human-created PR from `loreli → main` rolls up all agent work for final review.
+
+## PR Quality Gates
+
+`pr` config controls pre-PR quality enforcement in the `pr` MCP tool (`action: create`).
+
+```yaml
+pr:
+  validation:
+    command: npm test
+  selfReview:
+    enabled: true
+```
+
+- `pr.validation.command`: defaults to `npm test` and runs in the action agent workspace before PR creation. Non-zero exit blocks `pr/create` and returns command output.
+- `pr.selfReview.enabled`: defaults to `true` and switches `pr/create` into a two-step flow. First call returns a diff/stat preview. Second call must pass `confirm: true` to proceed.
+
+## Feedback HITL
+
+`feedback.hitl` controls per-category Human In The Loop escalation for feedback-driven PRs at merge time. It accepts three shapes:
+
+- **`false`** (default) — no HITL on feedback-driven PRs; they merge after agent sign-off.
+- **`true`** — HITL on all feedback-driven PRs; every such PR requires human approval before merge.
+- **`['architecture', 'security']`** — HITL only for listed categories; PRs driven by feedback in those categories require human approval; others auto-merge after agent sign-off.
+
+`merge.hitl` takes global precedence. When `merge.hitl` is `true`, all PRs (including feedback-driven ones) require human approval regardless of `feedback.hitl`.
+
+## Built-in Defaults
+
+Every configurable value has a default in `defaults.js`. These are the lowest-priority layer and apply when no other layer provides a value. Backend model defaults may be overridden at runtime by auto-discovery (see [Model Discovery](#model-discovery)):
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `repo` | `undefined` | Optional repository slug fallback (`owner/name`) for standalone tool contexts |
+| `theme` | `transformers` | Agent naming theme (`string` or `string[]` for random per work item) |
+| `reviewers` | `[]` | Human reviewers (empty = auto-merge) |
+| `model` | `balanced` | Default model alias |
+| `backends.claude.models.fast.anthropic` | `claude-haiku-4-5-20251001` | Claude fast tier |
+| `backends.claude.models.balanced.anthropic` | `claude-sonnet-4-5-20250929` | Claude balanced tier |
+| `backends.claude.models.powerful.anthropic` | `claude-opus-4-5-20251101` | Claude powerful tier |
+| `backends.codex.models.fast.openai` | `gpt-5-mini` | Codex fast tier |
+| `backends.codex.models.balanced.openai` | `gpt-5.1-codex` | Codex balanced tier |
+| `backends.codex.models.powerful.openai` | `gpt-5.2-pro` | Codex powerful tier |
+| `backends.cursor.models.fast.anthropic` | `sonnet-4.5` | Cursor fast anthropic |
+| `backends.cursor.models.balanced.anthropic` | `sonnet-4.5-thinking` | Cursor balanced anthropic |
+| `backends.cursor.models.powerful.anthropic` | `opus-4.6-thinking` | Cursor powerful anthropic |
+| `backends.{name}.env` | *(none)* | Backend-specific env var overrides (flat string map) |
+| `agents.disallowedTools` | `['gh', 'curl']` | Commands agents cannot execute |
+| `scaling.maxAgents` | `8` | Global cap — max agents across all roles |
+| `scaling.maxPerTick` | `2` | Max new agents spawned per reactor tick |
+| `scaling.cooldown` | `30000` | Min time between spawns for same role (ms) |
+| `merge.method` | `squash` | PR merge method |
+| `merge.hitl` | `false` | HITL mode: `false` = auto-merge, `true` = human reviewers |
+| `feedback.hitl` | `false` | Per-category HITL for feedback-driven PRs: `false` = none, `true` = all, `string[]` = listed categories only |
+| `merge.base` | `main` | Default PR base branch (scaffolding template sets `loreli` for safety — agents work on a dedicated branch, not main) |
+| `pr.validation.command` | `npm test` | Default shell command run before `pr/create`; non-zero exit blocks PR creation |
+| `pr.selfReview.enabled` | `true` | Require two-step self-review flow (`create` preview, then `create` with `confirm=true`) before PR creation |
+| `workflows.action.model` | `balanced` | Action agent model tier |
+| `workflows.action.maxAgents` | `3` | Max concurrent action agents |
+| `workflows.reviewer.model` | `balanced` | Reviewer agent model tier |
+| `workflows.reviewer.maxAgents` | `2` | Max concurrent reviewer agents |
+| `workflows.reviewer.trace.enabled` | `true` | Reviewer trace capture |
+| `workflows.reviewer.trace.maxOutputChars` | `4000` | Reviewer trace output cap |
+| `workflows.risk.model` | `fast` | Risk agent model tier |
+| `workflows.risk.maxAgents` | `3` | Max concurrent risk agents |
+| `workflows.risk.skip` | `false` | Skip mandatory risk verdict checks |
+| `workflows.risk.trace.enabled` | `true` | Risk trace capture |
+| `workflows.risk.trace.maxOutputChars` | `2000` | Risk trace output cap |
+| `workflows.planner.model` | `powerful` | Planner agent model tier |
+| `workflows.planner.maxAgents` | `1` | Max concurrent planner agents |
+| `workflows.planner.trace.enabled` | `true` | Planner trace capture |
+| `workflows.planner.trace.maxOutputChars` | `4000` | Planner trace output cap |
+| `workflows.{role}.prompt` | `undefined` | Custom prompt file for role (relative to repo root) |
+| `timeouts.stall` | `600000` | Agent stall detection (ms) |
+| `timeouts.shutdown` | `60000` | Graceful shutdown timeout (ms) |
+| `timeouts.poll` | `2000` | Poll interval (ms) |
+| `timeouts.rapidDeath` | `15000` | Spawn-window backend failure detection delay (ms) |
+| `timeouts.proxyDiscovery` | `5000` | Proxy model discovery HTTP timeout (ms) |
+| `timeouts.nudge` | `true` | Enable/disable tier-1 stall nudge messages |
+| `log.level` | `info` | Console log level |
+| `log.maxSize` | `10485760` | Max log file size (bytes) |
+| `log.maxFiles` | `3` | Rotated log file count |
+| `proofOfLife.timeout` | `300000` | Proof-of-life response timeout (ms, default 5m) |
+| `cleanup.retention` | `43200000` | Prune sessions older than this (ms, default 12h) |
+| `cleanup.autoprune` | `true` | Run prune at start |
+| `tmux.session` | `loreli` | Tmux session name |
+| `tmux.capture` | `500` | Pane capture history lines |
+
+## Environment Variable Mapping
+
+Only a subset of config values can be overridden via environment variables. These variables can come from the shell or from a `.env` file loaded via `loadEnv()`:
+
+| Config Path | Environment Variable | Purpose |
+|-------------|---------------------|---------|
+| `repo` | `LORELI_REPO` | Repository fallback (`owner/name`) for tool contexts before `start` |
+| `log.level` | `LORELI_LOG_LEVEL` | Override default log level |
+| `github.token` | `GITHUB_TOKEN` | GitHub API token for hub |
+
+Environment variables sit between the file layer and built-in defaults in resolution priority. Shell-set variables take precedence over `.env` file values.
+
+Additional env vars recognized by other packages but not routed through `Config.get()`:
+
+| Variable | Package | Purpose |
+|----------|---------|---------|
+| `LORELI_HOME` | mcp, agent, log | Override `~/.loreli/` base storage directory |
+| `LORELI_TEST_REPO` | tests | GitHub repo for integration tests (`owner/name`) |
+
+Copy `.env.example` from the project root to `.env` for local development. See the root README for the full list.
+
+## Backend Environment Variables
+
+Each backend can declare environment variable overrides in `loreli.yml` under `backends.{name}.env`. These are exported in launcher scripts before spawning the CLI agent in tmux.
+
+At runtime, the agent package's `models.env()` function merges two layers:
+
+1. **Inherited** — `process.env` vars matching the backend's known prefixes are collected automatically
+2. **Config overrides** — `backends.{name}.env` from `loreli.yml` or `config.merge()` take precedence on key collision
+
+| Backend | Inherited Prefixes |
+|---------|-------------------|
+| `claude` | `ANTHROPIC_*`, `CLAUDE_*` |
+| `codex` | `OPENAI_*`, `CODEX_*` |
+| `cursor` | `ANTHROPIC_*`, `OPENAI_*`, `CLAUDE_*`, `CURSOR_*` |
+
+This means critical variables like `ANTHROPIC_BASE_URL` (proxy URL), `ANTHROPIC_AUTH_TOKEN`, and `CLAUDE_CODE_DISABLE_EXPERIMENTAL_BETAS` are forwarded from the orchestrator's environment into tmux-spawned agents without explicit config — but can be overridden in `loreli.yml` when needed:
+
+```yaml
+backends:
+  claude:
+    env:
+      ANTHROPIC_BASE_URL: https://your-proxy.example.com/v1
+  codex:
+    env:
+      OPENAI_BASE_URL: https://your-proxy.example.com/v1
+```
+
+The `env` section is a flat string-to-string map. Non-string values and empty objects are silently discarded by schema validation.
+
+## Model Discovery
+
+At startup, `BackendRegistry.discover()` probes available backends for their supported models. This enables automatic tier classification without relying solely on static defaults that may become stale.
+
+### Resolution Chain
+
+Model aliases (`fast`, `balanced`, `powerful`) resolve through four layers:
+
+1. **Config override** — `backends.{name}.models.{alias}.{provider}` from `loreli.yml`. Always wins. Required for LiteLLM/proxy setups where model names differ from upstream.
+2. **Runtime discovery** — models discovered from backend CLIs and configured proxy endpoints. `cursor-agent` uses `--list-models`; `claude`/`codex` query OpenAI-compatible model listing (`/v1/models` with `/models` fallback) when their base URL overrides are configured.
+3. **Static defaults** — built-in values from `defaults.js`. When discovery data is available, static fallbacks are validated against the discovered list. Invalid IDs trigger a warning and fall back to the backend's default discovered model.
+4. **Pass-through** — exact model strings bypass resolution entirely.
+
+### Discovery by Backend
+
+| Backend | Method | Notes |
+|---------|--------|-------|
+| `cursor-agent` | `--list-models` CLI flag | Parseable output, classified into tiers per provider |
+| `claude` | Proxy model listing (`/v1/models` / `/models`) when `ANTHROPIC_BASE_URL` is configured | Auth key order: `ANTHROPIC_API_KEY`, then `OPENAI_API_KEY` |
+| `codex` | Proxy model listing (`/v1/models` / `/models`) when `OPENAI_BASE_URL` is configured | Auth key order: `OPENAI_API_KEY`, then `ANTHROPIC_API_KEY` |
+
+### Validation
+
+When discovery data is available, resolved model IDs are validated against the discovered model list. This catches stale defaults, typos, and models removed by providers. When validation fails, the backend's default model is used and a warning is logged.
+
+### LiteLLM / Proxy Override
+
+When backends route through a LiteLLM proxy or custom gateway, override model names in `loreli.yml`:
+
+```yaml
+backends:
+  claude:
+    env:
+      ANTHROPIC_BASE_URL: https://your-litellm.example.com/v1
+    models:
+      fast:
+        anthropic: litellm/haiku
+      balanced:
+        anthropic: litellm/sonnet
+      powerful:
+        anthropic: litellm/opus
+```
+
+Config overrides take precedence over both discovery and static defaults. See [packages/agent/README.md](../agent/README.md) for the full model resolution API reference.
+
+## Tool Blocking
+
+Agents can bypass Loreli's MCP guardrails (stamping, role guards, label enforcement) by using raw CLI tools like `gh` or `curl` to interact with GitHub directly. The `agents.disallowedTools` config prevents this by blocking specified commands across all CLI backends.
+
+### How It Works
+
+The deny list is enforced through each backend's native mechanism:
+
+| Backend | Enforcement | Source |
+|---------|-------------|--------|
+| Claude Code | `--disallowedTools` CLI flag + `PreToolUse` hooks | [Hooks guide](https://code.claude.com/docs/en/hooks-guide) |
+| Cursor Agent | `beforeShellExecution` hooks (`.cursor/hooks.json`) | [Cursor hooks](https://cursor.com/docs/agent/hooks) |
+| Codex CLI | `rules.prefix_rules` via `-c` flags | [Codex config](https://developers.openai.com/codex/config-reference) |
+
+When `prepare()` scaffolds an agent workspace with a non-empty deny list, it creates/updates three enforcement files:
+
+- **`.loreli/deny.sh`** — Common deny script used by both Claude and Cursor hooks. Reads JSON from stdin, extracts the command, and exits with code 2 (block) if the first token matches a denied command. Exit code 2 is the universal block signal recognized by both Claude Code and Cursor Agent. Always overwritten when the deny list changes.
+- **`.claude/settings.local.json`** — Claude Code project hooks config referencing `deny.sh` for `PreToolUse` events on Bash tools. **Merged** into existing file — user-defined hooks and non-hook settings (e.g. `permissions`) are preserved.
+- **`.cursor/hooks.json`** — Cursor Agent hooks config referencing `deny.sh` for `beforeShellExecution` events with a regex matcher. **Merged** into existing file — user-defined hooks are preserved.
+
+Loreli's hook entry is identified by its reference to `deny.sh` in the command string. On subsequent runs, the existing Loreli entry is updated in place (e.g. when the deny list changes) rather than duplicated.
+
+### Customizing the Deny List
+
+Override the default deny list in `loreli.yml`:
+
+```yaml
+agents:
+  disallowedTools:
+    - gh
+    - curl
+    - wget
+```
+
+To disable tool blocking entirely, set an empty array:
+
+```yaml
+agents:
+  disallowedTools: []
+```
+
+## Input Validation (`check`)
+
+The `check` module provides strict validators for tool arguments, preventing invalid inputs before any side effects occur. All validators throw descriptive errors on invalid input and return the validated value on success.
+
+```js
+import { check } from 'loreli/config';
+
+check.repo('owner/repo');     // returns 'owner/repo'
+check.repo('invalid');         // throws: Invalid repository format
+
+check.name('optimus-0');       // returns 'optimus-0'
+check.name('x'.repeat(65));   // throws: Agent name too long
+
+check.role('action');          // returns 'action'
+check.role('admin');           // throws: Invalid role
+
+check.theme('transformers');   // returns 'transformers'
+check.theme(['pokemon', 'marvel']); // returns ['pokemon', 'marvel']
+check.provider('anthropic');   // returns 'anthropic'
+check.positive(42, 'PR');      // returns 42
+check.positive(-1, 'count');  // throws: count must be a positive number
+```
+
+### API
+
+| Function | Rule | Error |
+|----------|------|-------|
+| `check.repo(str)` | `owner/name` format, alphanumeric + `.` `-` `_` | `Invalid repository format` |
+| `check.name(str)` | `[A-Za-z0-9_-]+`, max 64 chars | `Agent name too long` / `Invalid agent name` |
+| `check.role(str)` | `planner` \| `action` \| `reviewer` | `Invalid role` |
+| `check.theme(str\|str[])` | Valid theme name(s); arrays must be non-empty | `Invalid theme` / `Theme list must not be empty` |
+| `check.provider(str)` | `openai` \| `anthropic` \| `cursor-openai` \| `cursor-anthropic` | `Invalid provider` |
+| `check.positive(n, label)` | Finite positive number | `{label} must be a positive number` |
+
+All validators follow the pattern: required string → format check → return validated value. `null`, `undefined`, and empty strings are rejected with "required" errors.
+
+## Schema Validation
+
+The `validate(raw)` function normalizes raw YAML content:
+
+- Strips unknown keys
+- Validates types (strings, numbers, arrays of strings)
+- `theme` accepts both a string and an array of strings (single-element arrays collapse to a string)
+- Returns only known, valid fields
+
+Invalid values are silently discarded, allowing partial `loreli.yml` files to work correctly.
+
+## Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| `loreli.yml` missing | `load()` returns `false`, defaults apply |
+| Malformed YAML | `load()` returns `false`, defaults apply |
+| Invalid type in config | `validate()` strips the key, default applies |
+| Unknown keys in YAML | Silently ignored |