loreli 0.0.0 → 1.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 `review.skipRiskAssessment: 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 `skipRiskAssessment` 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).