loreli 0.0.0 → 1.0.0

package/packages/planner/README.md

@@ -0,0 +1,168 @@
+# loreli/planner
+
+Planning workflow for Loreli's orchestration pipeline. Extends the `Workflow` base class to manage planner agents — dispatching objectives, adversarial plan review via yin/yang pairing, and promoting approved discussions to issues.
+
+## Research Findings
+
+No existing npm packages cover planning workflow with cross-provider adversarial review. This is domain-specific to Loreli's yin/yang agent model.
+
+## Architecture
+
+The planner uses **GitHub Discussions** as its planning primitive. Discussions in a "Loreli" category serve as the workspace where plans are proposed, reviewed, revised, and eventually promoted to real issues.
+
+Labels act as a state machine on each discussion:
+
+| State | Labels Present | Next Action |
+|-------|---------------|-------------|
+| Needs review | _(none)_ | Reviewer dispatched |
+| Changes requested | `loreli:changes-requested` | Planner revises |
+| Blocked | `loreli:blocked` + `loreli:changes-requested` | Parked until dependency resolves |
+| Approved | `loreli:approved` | Promoted to issue |
+
+The reactor tick pipeline runs handlers in order: **planner-hydrate → planner-recover → unblock → revise → review → promote → link → planner-reap**. `unblock` runs before review so freshly unblocked discussions can enter review on the same tick.
+
+```mermaid
+flowchart LR
+  H["planner-hydrate"] --> R["planner-recover"]
+  R --> U["unblock"]
+  U --> V["revise"]
+  V --> W["review"]
+  W --> P["promote"]
+  P --> L["link"]
+  L --> X["planner-reap"]
+```
+
+### Blocker Detection
+
+When `revise()` processes a `changes-requested` discussion, it scans comments for `#N` issue references and uses keyword-based heuristics (via `knowledge.classifyRefs()`) to distinguish dependency blockers from informational references. No LLM dependency.
+
+- **Blockers** (e.g., "depends on #5 being merged") — verified against `hub.issue()`. If open, the discussion is parked with `loreli:blocked`.
+- **Informational** (e.g., "see #3 for prior art") — ignored, normal revision continues.
+
+The `unblock()` handler checks blocked discussions every tick. When all blockers resolve, it removes both labels so the discussion re-enters review fresh.
+
+### Tiebreaker Protocol
+
+When a discussion has no external blockers but cycles through `changes-requested` indefinitely, `_revisionRounds` tracks how many times `revise()` has processed it. Behavior varies by round count vs `watch.maxRounds` (default 3):
+
+| Condition | Behavior |
+|-----------|----------|
+| `rounds < maxRounds` | Normal revision dispatch |
+| `rounds === maxRounds` | Tiebreaker revision — planner gets a focused prompt to fundamentally restructure the plan |
+| `rounds > maxRounds` | HITL escalation — `loreli:needs-attention` applied and human reviewers notified |
+
+The reviewer prompt also changes based on rounds: normal reviews use `plan-reviewer.md`, tiebreaker reviews use `tiebreaker-reviewer.md` with pragmatic evaluation guidance.
+
+### Dedicated Reviewer Prompts
+
+Plan review uses two dedicated prompts (separate from the PR-review `reviewer.md`):
+
+| Template | Location | Purpose |
+|----------|----------|---------|
+| `plan-reviewer.md` | `prompts/` | Standard plan review — scope, clarity, feasibility |
+| `tiebreaker-reviewer.md` | `prompts/` | Pragmatic tiebreaker review — approve if directionally correct |
+
+## API Reference
+
+### `PlannerWorkflow` (extends Workflow)
+
+```js
+import { PlannerWorkflow } from 'loreli/planner';
+
+const planner = new PlannerWorkflow(orchestrator, hub);
+```
+
+The constructor accepts the orchestrator (EventEmitter) and hub (GitHub API).
+
+#### Static Properties
+
+| Property | Value | Description |
+|----------|-------|-------------|
+| `role` | `'planner'` | Agent role this workflow manages |
+| `template` | `prompts/planner.md` | Mustache template for planner prompts |
+
+### Methods
+
+#### `planner.plan(repo, objective)` → Promise\<{planners, categoryId}\>
+
+Dispatch the planning objective to all available planner agents. Finds the "Loreli" discussion category, renders the planner prompt with the objective, and sends to each agent.
+
+The example below shows how `start_planning` triggers the planning workflow. The orchestrator coordinates agent lifecycle, while the planner package owns the planning logic:
+
+```js
+const result = await planner.plan('owner/repo', 'Build auth module');
+// { planners: ['optimus-0'], categoryId: 'DIC_kwDO...' }
+```
+
+#### `planner.unblock(repo)` → Promise\<void\>
+
+Check blocked discussions for resolved dependencies. For each discussion in the `_blocked` map, verifies whether all blocking issues/PRs have been closed. When resolved, removes `loreli:blocked` and `loreli:changes-requested` labels so the discussion re-enters review.
+
+Runs FIRST in the tick pipeline.
+
+#### `planner.revise(repo)` → Promise\<Array\<{number, planner}\>\>
+
+Handle discussions with `loreli:changes-requested` label (excluding blocked discussions). For each discussion:
+
+1. Scans comments for issue references and classifies them using keyword heuristics (`extractRefs` + `classifyRefs`)
+2. Parks blocked discussions (applies `loreli:blocked`, stores in `_blocked` map)
+3. Increments `_revisionRounds` for non-blocked discussions
+4. At `maxRounds`: dispatches tiebreaker revision with special prompt
+5. Beyond `maxRounds`: HITL escalation — applies `loreli:needs-attention` and notifies human reviewers
+6. Below `maxRounds`: dispatches normal revision
+
+Runs SECOND in the tick pipeline. Returns an empty array if no discussions need revision.
+
+#### `planner.review(repo)` → Promise\<{reviewer, discussions}\>
+
+Dispatch unlabeled discussions (no `loreli:approved`, `loreli:changes-requested`, or `loreli:blocked`) to a reviewer. In dual-side mode it prefers yin/yang pairing; in single-side mode it falls back to same-side reviewer enlistment. Selects the reviewer template based on revision round count: `plan-reviewer.md` for normal reviews, `tiebreaker-reviewer.md` when `_revisionRounds >= maxRounds`.
+
+Returns `{ reviewer: null, discussions: 0 }` when no reviewer can be determined.
+
+#### `planner.promote(repo)` → Promise\<Array\<{number, title}\>\>
+
+Convert approved discussions (with `loreli:approved` label) to real GitHub issues. Posts a closing comment linking to the new issue, then closes and locks the discussion.
+
+#### `planner.escalate(repo, title, body, fallbackIdentity?)` → Promise\<{discussionId, categoryId}\>
+
+Signal a concern or feature idea by creating a discussion in the Loreli category. The discussion enters the standard review → revise → approve → promote pipeline.
+
+### Reactor Handlers
+
+The planner registers eight handlers with the orchestrator's reactor:
+
+```js
+planner.reactor()
+// → {
+//   'planner-hydrate': fn,
+//   'planner-recover': fn,
+//   unblock: fn,
+//   revise: fn,
+//   review: fn,
+//   promote: fn,
+//   link: fn,
+//   'planner-reap': fn
+// }
+```
+
+### Events
+
+The planner subscribes to no orchestrator events currently. All coordination happens through explicit method calls from the MCP tools layer.
+
+## Errors
+
+| Error | When | Resolution |
+|-------|------|------------|
+| `No planner agents available` | plan() called with no planner agents | Add a planner agent first |
+| `Discussion category "Loreli" not found` | plan() called without the Loreli category | Enable GitHub Discussions and create the category in repo settings |
+| `Cannot escalate without an identity` | escalate() called without agents or fallback identity | Add at least one agent before escalating |
+
+## Autonomous Operation
+
+Planner 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**: Plan dispatch, adversarial plan review, discussion revision, discussion promotion, planner prompt rendering.
+
+**Out of scope**: Agent lifecycle, escalation UI (handled by MCP tools), discussion category creation (manual via GitHub settings).