loreli 0.0.0 → 2.0.0

package/packages/mcp/scaffolding/loreli.yml

@@ -0,0 +1,491 @@
+# 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 frequently times out on healthy but slow networks (increase),
+  #         or startup blocks too long on unreachable 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
+
+# --- 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
+
+  # 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
+
+# --- Classification ---
+classify:
+  # classify.model
+  # What: Model tier used for non-interactive classification prompts.
+  # Impact: Higher tiers may classify more accurately but cost more and respond slower.
+  # Signal: Misclassified pane states/feedback or excessive latency/cost.
+  # Change when: You want a different speed/accuracy trade-off for classification tasks.
+  model: fast
+
+  # classify.maxLines
+  # What: Max pane lines captured for classifier input.
+  # Impact: Higher values provide more context but increase token usage and prompt size.
+  # Signal: Classifier misses important terminal context (increase), or prompts are noisy/too large (decrease).
+  # Change when: Terminal-state classification needs more or less surrounding context.
+  maxLines: 100
+
+  # classify.timeout
+  # What: Timeout for non-interactive classifier calls.
+  # Impact: Higher values tolerate cold starts; lower values fail fast on stuck backends.
+  # Signal: Frequent classifier timeouts on healthy backends (increase), or long stalls waiting for dead ones (decrease).
+  # Change when: Your classifier backends are slower or faster than the default.
+  timeout: 30s
+
+  # classify.maxRetries
+  # What: Max consecutive classifier failures before the orchestrator gives up and escalates.
+  # Impact: Higher values are more tolerant of transient failures; lower values fail closed sooner.
+  # Signal: Temporary classifier hiccups cause unnecessary kills/escalations (increase), or repeated failures waste time (decrease).
+  # Change when: You need a stricter or more forgiving classifier failure budget.
+  maxRetries: 5
+
+# --- 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
+
+# --- 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
+
+# --- Per-workflow configuration ---
+# workflows.{role}
+# What: Per-role settings consolidating model tier, agent cap, prompt override, trace, and skip flags.
+# Impact: Each workflow role can be tuned independently — model quality, parallelism, and observability.
+# Signal: Different roles need different cost/quality trade-offs, scaling limits, or trace verbosity.
+# Change when: You want per-role model tiers, scaling, custom prompts, or trace settings.
+workflows:
+  action:
+    # workflows.action.model
+    # What: Model tier for action agents (implementation work).
+    # Impact: Controls quality/cost of code generation.
+    # Change when: You want stronger/cheaper implementation agents.
+    model: balanced
+
+    # workflows.action.maxAgents
+    # What: Max concurrent action agents.
+    # Impact: Controls parallel implementation throughput.
+    # Change when: Work backlog is implementation-heavy.
+    maxAgents: 3
+
+    # workflows.action.prompt
+    # What: Repo-local prompt file override for action agents.
+    # Impact: Changes agent instructions without code changes.
+    # Change when: You need project-specific coding guardrails.
+    # prompt: .loreli/action.md
+
+  reviewer:
+    # workflows.reviewer.model
+    # What: Model tier for reviewer agents.
+    # Change when: You want stronger/cheaper review agents.
+    model: balanced
+    maxAgents: 2
+    # prompt: .loreli/reviewer.md
+    trace:
+      enabled: true
+      maxOutputChars: 4000
+
+  risk:
+    # workflows.risk.model
+    # What: Model tier for risk assessment agents.
+    # Change when: Risk evaluation needs deeper reasoning (powerful) or is fine with fast triage (fast).
+    model: fast
+    maxAgents: 3
+
+    # workflows.risk.skip
+    # What: Skips mandatory risk verdict checks in review flow.
+    # Impact: Faster review path with less explicit risk gating.
+    # Change when: You intentionally prefer speed over formal risk signoff.
+    skip: false
+    trace:
+      enabled: true
+      maxOutputChars: 2000
+
+  planner:
+    # workflows.planner.model
+    # What: Model tier for planner agents.
+    # Change when: Planning quality needs deeper reasoning.
+    model: powerful
+    maxAgents: 1
+    # prompt: .loreli/planner.md
+    trace:
+      enabled: true
+      maxOutputChars: 4000
+
+# --- 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

package/packages/mcp/scaffolding/mcp-configs/.codex/config.toml

@@ -0,0 +1,4 @@
+[mcp_servers.loreli]
+command = "npx"
+args = ["loreli", "mcp"]
+env_vars = ["GITHUB_TOKEN"]

package/packages/mcp/scaffolding/mcp-configs/.cursor/mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "loreli": {
+      "command": "npx",
+      "args": [
+        "loreli",
+        "mcp"
+      ],
+      "env": {
+        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
+      }
+    }
+  }
+}

package/packages/mcp/scaffolding/mcp-configs/.mcp.json

@@ -0,0 +1,14 @@
+{
+  "mcpServers": {
+    "loreli": {
+      "command": "npx",
+      "args": [
+        "loreli",
+        "mcp"
+      ],
+      "env": {
+        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
+      }
+    }
+  }
+}

package/packages/mcp/scaffolding/pull-request.md

@@ -0,0 +1,23 @@
+## Summary
+
+Brief description of what this PR does and why.
+
+## Changes
+
+- List the key changes made in this PR.
+
+## Testing
+
+- [ ] Tests added/updated
+- [ ] Manual testing performed
+- [ ] Edge cases considered
+
+## Issue Reference
+
+Closes #
+
+## Sign-off
+
+- [ ] Code follows project conventions
+- [ ] Documentation updated
+- [ ] No scope creep beyond the referenced issue