loreli 0.0.0 → 1.0.0

package/packages/mcp/scaffolding/ISSUE_TEMPLATE/loreli.yml

@@ -0,0 +1,83 @@
+name: Loreli Work Item
+description: Structured work item for Loreli agent orchestration. Issues created with this template are automatically labeled for agent dispatch.
+title: "[Loreli]: "
+labels: ["loreli"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        This template produces issues that Loreli agents can act on directly.
+        Write each section as if briefing an engineer who has never seen this
+        codebase — specific, testable, and unambiguous.
+
+  - type: textarea
+    id: objective
+    attributes:
+      label: Objective
+      description: What needs to be done, in one sentence. Be precise — this becomes the agent's mission.
+      placeholder: "Add exponential backoff retry logic to the GitHub API client for transient failures."
+    validations:
+      required: true
+
+  - type: textarea
+    id: acceptance
+    attributes:
+      label: Acceptance Criteria
+      description: >
+        Specific, testable conditions that define "done". Each criterion must be
+        independently verifiable by someone who did not write the code. Aim for
+        3+ criteria — vague items like "works correctly" will be rejected.
+      placeholder: |
+        - [ ] Retries on 429 and 5xx status codes, up to 3 attempts.
+        - [ ] Uses exponential backoff: 1s, 2s, 4s base delays with jitter.
+        - [ ] Non-retryable errors (4xx except 429) propagate immediately.
+        - [ ] Retry attempts are logged with attempt number and delay.
+    validations:
+      required: true
+
+  - type: textarea
+    id: testing
+    attributes:
+      label: Testing Strategy
+      description: >
+        Concrete test scenarios to write before implementation (TDD). Name
+        specific inputs, expected behaviors, and edge cases. Agents write
+        tests first — this section tells them what to test.
+      placeholder: |
+        - Test that 429 responses trigger retry with correct backoff timing.
+        - Test that 500/502/503 trigger retry.
+        - Test that 400/401/404 propagate immediately without retry.
+        - Test that max retries is respected and final error surfaces.
+        - Test jitter produces non-deterministic delays within expected bounds.
+    validations:
+      required: true
+
+  - type: textarea
+    id: scope
+    attributes:
+      label: Scope Boundaries
+      description: What is explicitly NOT included in this work. Helps agents avoid scope creep.
+      placeholder: "Does NOT include circuit breaker patterns, request queuing, or rate limit header parsing."
+    validations:
+      required: false
+
+  - type: textarea
+    id: dependencies
+    attributes:
+      label: Dependencies
+      description: Other issues, PRs, or external work this depends on. Link them if possible.
+      placeholder: "Depends on #42 (API client refactor)."
+    validations:
+      required: false
+
+  - type: dropdown
+    id: complexity
+    attributes:
+      label: Estimated Complexity
+      description: Rough sizing to help the orchestrator allocate the right agent tier.
+      options:
+        - Low
+        - Medium
+        - High
+    validations:
+      required: true

package/packages/mcp/scaffolding/loreli.yml

@@ -0,0 +1,453 @@
+# 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

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

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

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

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "loreli": {
+      "command": "npx",
+      "args": [
+        "loreli",
+        "mcp"
+      ]
+    }
+  }
+}

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

@@ -0,0 +1,11 @@
+{
+  "mcpServers": {
+    "loreli": {
+      "command": "npx",
+      "args": [
+        "loreli",
+        "mcp"
+      ]
+    }
+  }
+}

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