loreli 0.0.0 → 1.0.0

package/packages/config/README.md

@@ -0,0 +1,833 @@
+# 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.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('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
+
+# --- 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.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
+
+# --- Review policy ---
+review:
+  # review.skipRiskAssessment
+  # What: Skips mandatory risk verdict checks in review flow.
+  # Impact: Faster review path with less explicit risk gating.
+  # Signal: Teams intentionally bypassing risk gates for speed, or conversely incidents from insufficient risk checks (set false).
+  # Change when: You intentionally prefer speed over formal risk signoff.
+  skipRiskAssessment: false
+
+# --- Scaling policy ---
+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
+
+  maxPerRole:
+    # scaling.maxPerRole.action
+    # What: Max concurrent action agents.
+    # Impact: Controls parallel implementation throughput.
+    # Signal: Large implementation queue with insufficient coding capacity.
+    # Change when: Work backlog is implementation-heavy.
+    action: 3
+
+    # scaling.maxPerRole.reviewer
+    # What: Max concurrent reviewer agents.
+    # Impact: Controls review bottleneck relief.
+    # Signal: PRs are ready but waiting on reviewer assignment/completion.
+    # Change when: PR queue waits on reviews.
+    reviewer: 2
+
+    # scaling.maxPerRole.risk
+    # What: Max concurrent risk agents.
+    # Impact: Controls parallel risk assessment capacity.
+    # Signal: Reviews blocked on risk verdicts.
+    # Change when: Risk checks become the bottleneck.
+    risk: 3
+
+    # scaling.maxPerRole.planner
+    # What: Max concurrent planner agents.
+    # Impact: Limits parallel planning/discussion churn.
+    # Signal: Planning queue grows (increase) or discussion noise overwhelms maintainers (decrease).
+    # Change when: You want more/fewer simultaneous planning threads.
+    planner: 1
+
+  # 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.
+# Signal: Specific backend underperforms at current tier/provider mapping.
+# Change when: You need backend-specific model tuning.
+#
+# 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 ---
+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
+
+  workflows:
+    planner:
+      # trace.workflows.planner.enabled / maxOutputChars
+      # What: Planner-specific trace override.
+      # Impact: Fine-grained planner trace tuning.
+      # Signal: Planner traces need different verbosity than global behavior.
+      # Change when: Planner traces need different verbosity than global default.
+      enabled: true
+      maxOutputChars: 4000
+
+    reviewer:
+      # trace.workflows.reviewer.enabled / maxOutputChars
+      # What: Reviewer-specific trace override.
+      # Impact: Fine-grained reviewer trace tuning.
+      # Signal: Reviewer traces are too sparse for diagnosis or too noisy for signal extraction.
+      # Change when: Reviewer traces are too noisy or too sparse.
+      enabled: true
+      maxOutputChars: 4000
+
+    risk:
+      # trace.workflows.risk.enabled / maxOutputChars
+      # What: Risk-specific trace override.
+      # Impact: Fine-grained risk trace tuning.
+      # Signal: Risk reasoning context is truncated (increase) or over-captured (decrease).
+      # Change when: Risk traces need tighter/looser capture bounds.
+      enabled: true
+      maxOutputChars: 2000
+
+# --- 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
+
+# --- Prompt overrides ---
+# prompts.{role}
+# What: Repo-local prompt file overrides for each role.
+# Impact: Changes agent behavior/instructions without code changes.
+# Signal: Repeated instruction gaps that can be fixed with persistent repo-specific guidance.
+# Change when: You need project-specific guardrails or workflow guidance.
+# prompts:
+#   action: .loreli/action.md
+#   reviewer: .loreli/review.md
+#   planner: .loreli/planner.md
+#   risk: .loreli/risk.md
+
+# --- 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
+
+# --- 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.
+
+## 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:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `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.maxPerRole.action` | `3` | Max action agents |
+| `scaling.maxPerRole.reviewer` | `2` | Max reviewer agents |
+| `scaling.maxPerRole.risk` | `3` | Max risk agents |
+| `scaling.maxPerRole.planner` | `1` | Max planner agents |
+| `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 |
+| `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 |
+| `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.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 |
+| `prompts.action` | `undefined` | Custom prompt file for action agents (relative to repo root) |
+| `prompts.reviewer` | `undefined` | Custom prompt file for reviewer agents (relative to repo root) |
+| `prompts.planner` | `undefined` | Custom prompt file for planner agents (relative to repo root) |
+| `prompts.risk` | `undefined` | Custom prompt file for risk agents (relative to repo root) |
+| `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 |
+|-------------|---------------------|---------|
+| `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.
+
+## 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 |