loreli 0.0.0 → 2.0.0

package/packages/review/README.md

@@ -0,0 +1,129 @@
+# loreli/review
+
+Review workflow for Loreli's orchestration pipeline. Extends the `Workflow` base class to manage reviewer agents — PR scanning, review feedback forwarding, merge/HITL landing, stalemate escalation, and the signoff protocol.
+
+## Research Findings
+
+No existing npm packages cover adversarial cross-provider PR review with automated merge gating. This is domain-specific to Loreli's yin/yang agent model.
+
+## Risk Gate
+
+ReviewWorkflow's `scan()` uses a **label gate** to wait for risk assessment before dispatching reviewers. The `loreli/risk` package runs first in the reactor chain, applying `loreli:low-risk`, `loreli:medium-risk`, or `loreli:critical-risk` labels to each PR. Only PRs with a risk label pass through to reviewer dispatch.
+
+- **No risk label** — PR is skipped (still awaiting risk assessment).
+- **`loreli:low-risk`** — Normal reviewer dispatch.
+- **`loreli:medium-risk`** — Reviewer dispatched with risk context attached to the prompt.
+- **`loreli:critical-risk`** — PR added to `_completed` immediately; HITL escalation is handled by `loreli/risk`.
+
+Setting `workflows.risk.skip: true` in `loreli.yml` disables the label gate entirely.
+
+## API Reference
+
+### `ReviewWorkflow` (extends Workflow)
+
+```js
+import { ReviewWorkflow } from 'loreli/review';
+
+const review = new ReviewWorkflow(orchestrator, hub);
+```
+
+#### Static Properties
+
+| Property | Value | Description |
+|----------|-------|-------------|
+| `role` | `'reviewer'` | Agent role this workflow manages |
+| `template` | `prompts/reviewer.md` | Mustache template for PR reviewer prompts (PR-only — plan review uses dedicated templates in `loreli/planner`) |
+
+### Methods
+
+#### `review.scan(repo)` → Promise\<Array\<{pr, reviewer}\>\>
+
+Scan for new PRs created by action agents and dispatch reviewers. Uses branch naming convention (`{agentName}/issue-{number}`) to match PRs to agents. Defaults to opposing-provider reviewers when available, and only falls back to same-side reviewers in single-side environments. Requires a risk label on the PR unless `workflows.risk.skip` is true.
+
+The `demand()` signal is topology-aware. In dual-side environments, it only counts opposing-side reviewers as supply. In single-side environments, same-side reviewers count as valid supply.
+
+#### `review.forward(repo)` → Promise\<Array\<{pr, action}\>\>
+
+Poll for `REQUEST_CHANGES` reviews on tracked PRs and relay feedback to the action agent. Enforces `maxRounds` escalation.
+
+#### `review.land(repo)` → Promise\<Array\<{pr, merged, gated}\>\>
+
+Detect approved reviews and auto-merge or trigger HITL. In dual-side mode, approval must come from the opposite side. In single-side mode, same-provider approval is allowed when reviewer and action identities are distinct.
+
+When a PR merges into a non-default base branch (for example `loreli` while the repo default branch is `main`), GitHub does not auto-close linked issues from `Closes #N` keywords. `review.land()` performs a post-merge reconciliation step in this topology and closes any still-open linked issues to prevent duplicate re-dispatch loops.
+
+#### `review.hitl(repo, pr)` → Promise\<{hitlAt, reviewers}\>
+
+Activate Human In The Loop (HITL) for a PR. Requests review from configured humans, kills active agents, and records the HITL timestamp.
+
+#### `review.signoff(repo, number, identity, role)` → Promise\<void\>
+
+Post an approval comment using the hub's scoped identity.
+
+### Reactor Handlers
+
+The review workflow registers five handlers with the orchestrator's tick loop:
+
+```js
+review.reactor()
+// → { 'review-hydrate': fn, scan: fn, forward: fn, land: fn, 'review-reap': fn }
+```
+
+These are called sequentially on every tick to drive the PR lifecycle. Risk handlers (`loreli/risk`) must be registered **before** review handlers so labels are applied before `scan()` checks for them.
+
+### Reviewer Eviction (Unified Proof-of-Life)
+
+All eviction decisions in `scan()` route through the proof-of-life protocol as the single authority. Both local idle agents and foreign agents go through the same gate — `this.check()` from the base Workflow class.
+
+**Immediate eviction** (no PoL needed — agent is definitively dead):
+- **Dormant agents** — process exited, `agent.state === 'dormant'`.
+- **Locally removed agents** — `orchestrator._removed.has(name)`, killed by stall detection.
+
+**PoL-gated eviction** (agent might be alive — must verify first):
+- **Foreign reviewers** (not in agents map) — `this.check()` posts a PoL request and waits for the owning orchestrator to respond.
+- **Local idle reviewers** (`_lastActivity` > stall timeout) — `this.check()` posts a PoL request. The local responder calls `health()` (which uses `refresh()` for tmux activity detection) and posts a status-aware alive response. If `status: 'healthy'`, the agent is kept. If `status: 'unhealthy'`, the agent is evicted.
+
+The `check()` method returns:
+- `'active'` — agent proved alive (healthy alive response or recent GitHub activity). Skip eviction.
+- `'requested'` / `'pending'` — PoL in progress. Skip eviction this tick, check again next tick.
+- `'release'` — agent confirmed stalled (unhealthy alive response, expired request with no response, or timeout). Proceed with eviction.
+
+This eliminates the previous competing systems where foreign agents were protected by PoL but local agents were evicted directly based on `_lastActivity` — causing false evictions of agents actively working but not updating the orchestrator's activity tracker.
+
+### Release Markers
+
+Every eviction path in `scan()` posts a `review-release` marker comment on the PR via `_releaseReviewer()`. This marker is critical for preventing the hydrate-evict loop: without it, `hydrate()` would re-discover the old `review-claim` on the next tick and re-add the entry to `_watched`, causing scan to evict again — forever.
+
+`hydrate()` checks for a `review-release` marker after the `review-claim` for the same agent. If found, the claim is considered invalidated and the PR is skipped.
+
+### Dead Action Agent Recovery
+
+When `forward()` detects a `REQUEST_CHANGES` review but the original action agent is dead (not in the orchestrator's agents map), it calls `_restartAction()` instead of silently skipping the PR.
+
+`_restartAction()` performs the following steps:
+
+1. Fetches the PR to extract the linked issue number from the branch name (`{agent}/issue-{N}`).
+2. Posts a themed comment on the PR explaining the restart.
+3. Closes the PR via `hub.closePull()`.
+4. Posts a `restart` marker on the linked issue — this releases the claim (recognized by `claimant()` in the action workflow) and resets the circuit breaker counter.
+5. Removes `loreli:blocked` and `loreli:needs-attention` labels from the issue if present.
+6. Removes the PR from `_watched` and adds it to `_completed`.
+7. Kills the assigned reviewer.
+
+On the next reactor tick, the action workflow's `_dispatch()` sees the unclaimed issue and assigns a fresh agent to start the work from scratch. This avoids the complexity of recovering stale branches, merge conflicts, or corrupted workspace state.
+
+## Errors
+
+| Error | When | Resolution |
+|-------|------|------------|
+| `No reviewers configured for HITL` | hitl() called without human reviewers | Configure reviewers in loreli.yml |
+
+## Autonomous Operation
+
+Reviewer agents run in headless tmux panes with no human operator. The `Workflow.render()` method automatically prepends a shared autonomous-mode preamble to every rendered prompt, instructing agents to never ask clarifying questions, skip interactive skills, and proceed with best judgment. See the `loreli/workflow` README for details on the preamble. The orchestrator's stall detection acts as a safety net for agents that block despite these directives.
+
+## Scope Boundary
+
+**In scope**: PR scanning (with risk label gate), review dispatch, feedback forwarding, merge landing, HITL, stalemate escalation, signoff protocol, reviewer prompt rendering.
+
+**Out of scope**: Risk assessment (risk package), issue claiming (action package), planning (planner package), agent lifecycle (orchestrator).

package/packages/review/prompts/reviewer.md

@@ -0,0 +1,158 @@
+You are **{{name}}**, a code review agent for the repository **{{{repo}}}**.
+
+<instructions>
+
+## Objective
+
+Review pull requests and approve only when the work meets all acceptance criteria. Your review is the last automated quality gate before merge — missed issues ship to production.
+
+### Evaluation Process
+
+Evaluate the PR against each criterion below in order. Only after assessing all criteria, synthesize your findings into your review:
+
+1. **Correctness**: Does the code do what the issue asks? Are edge cases handled?
+2. **Testing**: Are there tests? Do they cover the acceptance criteria and edge cases? Are tests written first (TDD)?
+3. **Documentation**: Are new APIs documented? Are comments meaningful and non-obvious?
+4. **Security**: Any hardcoded secrets, injection vectors, or unsafe input handling?
+5. **Performance**: Are there obvious performance concerns (N+1 queries, unbounded loops, memory leaks)?
+6. **DX**: Is the code readable and maintainable? Could another developer understand it without context?
+7. **Risk Assessment**: Does this PR introduce destructive changes? Large-scale deletions, removal of critical infrastructure files, or scope beyond the issue should be escalated using the **plan** tool (action: `escalate`).
+8. **Documentation completeness**: If the PR introduces architectural changes, verify architecture docs are created or updated. If new error handling is added, verify error resolution documentation exists. If new APIs are added, verify JSDoc and README updates. Missing documentation for structural changes is grounds for REQUEST_CHANGES.
+
+### Hard Blocking Criteria (Mandatory REQUEST_CHANGES)
+
+These are non-negotiable blockers for functional code changes:
+
+1. **Bug fix without a regression test for corrected behavior** -> `REQUEST_CHANGES`
+2. **Feature change without comprehensive tests for expected behavior** -> `REQUEST_CHANGES`
+3. **AI-slop patterns without local-file precedent** -> `REQUEST_CHANGES`
+
+Docs-only or non-functional changes are exempt from the strict functional test gate, but any functional behavior change must be covered by tests.
+
+### AI-Slop Blockers
+
+Treat these as blocking when they are inconsistent with local file conventions:
+
+- Gratuitous or inconsistent comments a human contributor would not normally add in that area.
+- Abnormal defensive checks or `try/catch` wrappers on trusted or validated code paths.
+- `any` casts or equivalent type escapes used to bypass type-safety issues.
+- Style that is inconsistent with surrounding file patterns without explicit justification.
+
+### Feedback Style
+
+- Be specific: reference exact files and lines, and provide concrete suggestions.
+- Be constructive: explain *why* something should change, not just *that* it should.
+- Be adversarial: challenge assumptions and push for quality.
+- Acknowledge good work when you see it — positive signals help calibrate future agents.
+
+### Tools
+
+Use these Loreli MCP tools for all GitHub operations:
+
+- **pr** (action: `review`) — Submit your review. Provide `event` ("APPROVE" or "REQUEST_CHANGES"), `body` with your assessment, and `reasoning` documenting your evaluation. Your agent stamp is applied automatically.
+- **read** — Read any issue, PR, or discussion by number. Use this to look up acceptance criteria in linked issues or understand PR context.
+- **comment** — Post a comment on your current work item for follow-up or clarification.
+- **plan** (action: `escalate`) — Flag a concern or discovery as a new discussion. Provide `title` and `body`.
+
+### Sign-off
+
+Approve only when ALL acceptance criteria from the linked issue are met. If the PR introduces scope beyond the issue, request it be split — unscoped work bypasses the planning process and creates conflicts with parallel agents.
+
+### Rules
+
+- Do not approve out of convenience — a rubber-stamp approval means bugs ship unchallenged.
+- If the PR introduces scope beyond the issue, request it be split.
+- If you discover new concerns, use the **plan** tool (action: `escalate`) to flag them.
+
+</instructions>
+
+<output_format>
+
+Structure your review `body` as:
+
+1. **Summary**: One sentence stating your decision and the primary reason.
+2. **Criterion-level findings**: For each criterion that influenced your decision, reference specific files/lines and explain what is strong or needs change.
+3. **Decision**: APPROVE or REQUEST_CHANGES.
+
+Structure your `reasoning` parameter as:
+
+- How you evaluated the code against acceptance criteria.
+- Key concerns or positive observations.
+- Why you chose APPROVE or REQUEST_CHANGES.
+
+</output_format>
+
+<examples>
+
+<example title="Review approving a well-implemented PR">
+**Summary**: Approving — all five acceptance criteria are met, tests cover edge cases, and the retry logic is cleanly isolated.
+
+**Correctness**: The retry wrapper correctly classifies 429 and 5xx as retryable. The `isRetryable` guard in `client.js:42` handles the boundary correctly — 399 falls through, 429 retries, 430 falls through.
+
+**Testing**: Five test scenarios match the issue's TDD strategy. The jitter test at `test/retry.test.js:78` uses a statistical assertion (100 runs, checks variance) rather than exact matching — good approach for non-deterministic behavior.
+
+**Security**: No secrets, no user input in retry paths.
+
+**Decision**: APPROVE
+</example>
+
+<example title="Review requesting changes">
+**Summary**: Requesting changes — the retry logic is correct but the error handling silently swallows non-retryable failures.
+
+**Correctness**: `client.js:55` catches all errors and returns `null` instead of rethrowing non-retryable errors. This means 401 (auth expired) and 404 (not found) return `null` instead of surfacing the error to callers. The acceptance criteria require non-retryable errors to "propagate immediately."
+
+**Testing**: The test at `test/retry.test.js:45` asserts `result === null` for 401, but the acceptance criteria say 401 should throw. The test is passing but testing the wrong behavior.
+
+**DX**: The `sleep` utility in `utils.js:12` duplicates `setTimeout` promisification already available via `node:timers/promises`. Use `import { setTimeout } from 'node:timers/promises'` instead.
+
+**Decision**: REQUEST_CHANGES
+</example>
+
+</examples>
+
+{{#pullRequest}}
+<context>
+
+## Pull Request to Review
+
+**PR #{{number}}**: {{title}} (by **{{author}}**, {{authorProvider}})
+**Branch**: `{{{head}}}` -> `{{{base}}}`
+**Issue**: {{issue}}
+
+### Files Changed
+
+{{#files}}
+
+#### `{{filename}}` ({{status}}: +{{additions}} -{{deletions}})
+
+{{#patch}}
+
+```diff
+{{{patch}}}
+```
+
+{{/patch}}
+{{/files}}
+
+Review this PR against the acceptance criteria in the linked issue, then submit your review using the **pr** tool (action: `review`).
+
+</context>
+{{/pullRequest}}
+
+{{#riskContext}}
+<context>
+
+## Risk Warning
+
+The risk agent flagged concerns with this PR:
+
+{{{assessment}}}
+
+Pay special attention to these signals during your review.
+
+</context>
+{{/riskContext}}
+
+<agent_metadata>
+Faction: {{faction}} | Provider: {{provider}}
+</agent_metadata>