@revisium/orchestrator 0.1.0-alpha.9 → 0.1.0

package/README.md

@@ -1,202 +1,188 @@
-# agent-orchestrator
+<div align="center">
 
-Local orchestrator for software-development tasks driven by short-lived AI agents (architect → developer →
-reviewer → integrator), hosted in **NestJS**. **DBOS** owns durable progress — execution is crash-safe and resumes
-from the first unfinished step — while **Revisium** owns meaning: roles, policy, inbox, events. Workflow-as-data is
-a post-MVP goal; see [`docs/architecture-overview.md`](./docs/architecture-overview.md).
+# @revisium/orchestrator
 
-> 🚧 **Early alpha.** The end-to-end MVP works — create a run → plan gate → implement → review → PR → merge
-> gate — see [`docs/roadmap.md`](./docs/roadmap.md).
+Local-first orchestration for software-development work driven by short-lived agents.
 
-## Start here
+**Turn a task into a playbook-driven state machine.**
 
-- Repo context for agents: [`AGENTS.md`](./AGENTS.md)
-- Vision: [`docs/vision.md`](./docs/vision.md)
-- Architecture & invariants: [`docs/architecture-overview.md`](./docs/architecture-overview.md)
-- Docs index & roadmap: [`docs/README.md`](./docs/README.md) · [`docs/roadmap.md`](./docs/roadmap.md)
+[![License](https://img.shields.io/github/license/revisium/orchestrator?color=blue)](LICENSE)
+[![CI](https://github.com/revisium/orchestrator/actions/workflows/ci.yml/badge.svg)](https://github.com/revisium/orchestrator/actions/workflows/ci.yml)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=revisium_agent-orchestrator&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=revisium_agent-orchestrator)
+[![npm](https://img.shields.io/npm/v/@revisium/orchestrator?color=red)](https://www.npmjs.com/package/@revisium/orchestrator)
 
-## Local Development
+Part of the [Revisium](https://github.com/revisium/revisium) ecosystem.
 
-`revo` is one daemonized product. **`revo start`** brings up the whole stack — the standalone
-Revisium daemon plus the Revo host daemon that owns DBOS and serves the GraphQL + MCP front doors —
-and bootstraps the control-plane so it is ready to use. The CLI is lifecycle-only
-(`start` / `stop` / `status` / `restart` / `doctor` / `logs`); orchestration (runs, inbox, …) is
-reached over **MCP** (agents) or **GraphQL** (UI/scripts), both served by the daemon.
+</div>
 
-Run a source checkout alongside an installed package without collisions via a named **profile**
-(`--profile dev`, or `REVO_PROFILE=dev`): the `dev` profile shifts the whole port band off the
-`default` profile, so the two never share a port, data dir, or `dbos` database.
+```mermaid
+flowchart LR
+  task[Task]
+  playbook[Playbook]
+  machine[State machine]
+  outcome[Outcome]
 
-```sh
-pnpm install
-pnpm run revo -- start --profile dev    # standalone + host daemon, bootstrapped & ready
-pnpm run revo -- status --profile dev   # stack health summary
-pnpm run revo -- doctor --profile dev   # diagnose process / port / profile issues
-pnpm run revo -- logs --profile dev     # tail host + standalone logs; add -f to follow
-pnpm run revo -- restart --profile dev  # stop, then start
-pnpm run revo -- stop --profile dev
+  task --> playbook --> machine --> outcome
+
+  subgraph nodes[State machine nodes]
+    agent[Agent step] --> script[Script step] --> gate[Human gate] --> branch{Branch}
+    branch --> loop((Loop))
+    loop -. retry .-> agent
+    loop -. reroute .-> script
+  end
+
+  machine -. expands into .-> nodes
+  outcome --> pr[Pull request]
+  outcome --> evidence[Evidence]
+  outcome --> decisions[Decisions]
+  outcome --> history[Run history]
 ```
 
-| Knob | `default` (installed package) | `dev` (source checkout) |
-| --- | --- | --- |
-| data dir | `~/.revisium-orchestrator` | `~/.revisium-orchestrator-dev` |
-| standalone HTTP / Postgres | `19222` / `15440` | `19622` / `15840` |
-| Revo GraphQL | `19223` | `19623` |
-| DBOS database | `dbos` | `dbos_dev` |
+> Revo is in active development. The package is suitable for evaluation and local experimentation; do not treat
+> the public contract as stable yet.
 
-Any single knob can be overridden explicitly — `REVO_DATA_DIR` / `REVO_PORT` / `REVO_PG_PORT` /
-`REVO_GRAPHQL_PORT` / `REVO_DBOS_DB` — and an explicit env var always wins over the profile band.
+## Overview
 
-Connect an agent over MCP (`revo mcp` is a thin stdio bridge — it does not launch its own DBOS;
-if the daemon isn't already running, the bridge auto-starts it on first use; the profile comes
-from the process environment, not per-call args):
+Revo is a local control plane for agentic work. A caller creates a run, Revo selects a playbook, and the playbook
+executes as a state machine made of agent steps, script steps, human gates, branches, and loops.
 
-**Claude Code**
+The goal is not to replace coding agents. Revo coordinates them: it keeps state, records evidence, enforces gates,
+and gives humans a stable place to approve plans, resolve questions, inspect feedback, and decide when work is ready
+to ship.
 
-```sh
-# global install
-claude mcp add revo -- revo mcp
+## How It Works
+
+- **Playbooks define flow.** Roles, scripts, gates, verdicts, branches, and loop limits are data, not hidden prompt
+  convention.
+- **Agent steps are short-lived.** Each agent process receives current state and exits after one step.
+- **Script steps do deterministic work.** Automation such as integration, polling, and response actions stays outside
+  agent prompts.
+- **Human gates are state changes.** A plan approval, question answer, or merge approval resolves an inbox item and
+  resumes the run.
+- **Outputs are traceable.** Artifacts, evidence, decisions, attempts, cost, and run history are recorded for later
+  inspection.
+
+## Concepts
+
+| Term | Meaning |
+| --- | --- |
+| **Revo** | The local orchestrator and control plane for software-development runs. |
+| **Playbook** | A versioned bundle of roles, pipelines, policies, and routing rules. |
+| **Pipeline** | A state-machine template that defines the steps, gates, branches, loops, and terminal outcomes. |
+| **Role** | A named agent definition: prompt, model level, scope, runner, and allowed behavior. |
+| **Agent step** | A pipeline node that starts a short-lived coding agent through a role. |
+| **Script step** | A deterministic automation node used for integration, polling, readiness, or response actions. |
+| **Human gate** | A required decision or answer; the run parks until an inbox item is resolved. |
+| **Run** | One task moving through a selected playbook and pipeline. |
+| **Attempt** | One execution of one step; the unit for logs, verdicts, tokens, and cost. |
+| **MCP** | The local agent-facing tool bridge exposed by `revo mcp`. |
+| **GraphQL API** | The local API surface for UI and script integrations. |
+
+## Alpha Install
+
+The `@alpha` package is a prerelease for evaluating Revo locally. It uses the `default` profile:
 
-# dev checkout
-claude mcp add revo -- pnpm --dir "$PWD" run revo -- mcp
+```sh
+npm install -g @revisium/orchestrator@alpha
+revo start
+revo status
+revo doctor
+revo logs
+revo stop
 ```
 
-**Codex CLI** (`codex mcp add` or edit `~/.codex/config.toml` directly)
+Connect an MCP-capable agent to the installed binary:
 
 ```sh
-# global install
 codex mcp add revo -- revo mcp
-
-# dev checkout (use an absolute path — $PWD does not expand in TOML args)
-codex mcp add revo-dev -- pnpm --dir /abs/path/to/agent-orchestrator run revo -- mcp
+claude mcp add revo -- revo mcp
 ```
 
-To use a non-`default` profile with Codex, append `--env REVO_PROFILE=dev` (and the other
-dev-band vars; see the JSON block under **Live Run Observability Smoke**) to `codex mcp add`,
-or export the vars in the shell before launching Codex — stdio servers inherit the parent
-environment. Equivalent TOML for the global install form:
+Default local ports:
 
-```toml
-# ~/.codex/config.toml
-[mcp_servers.revo]
-command = "revo"     # or the absolute path from `which revo` if revo is not on Codex's PATH
-args = ["mcp"]
-```
+| Service | Port |
+| --- | --- |
+| Revisium standalone HTTP | `19222` |
+| embedded Postgres | `15440` |
+| Revo GraphQL | `19223` |
 
-**Verify the connection** — run `claude mcp list` or `codex mcp list` to confirm the server
-appears, then have the agent call `get_status` for a healthy JSON status reply. `list_pipelines`
-is a good read-only alternative.
+GraphQL is available at `http://127.0.0.1:19223/graphql` in the default profile. The target contract is documented in
+[docs/specs/graphql-admin-api-v1.spec.md](./docs/specs/graphql-admin-api-v1.spec.md), and the committed SDL is
+[src/api/graphql-api/schema.graphql](./src/api/graphql-api/schema.graphql).
 
-Run the local verification gates:
+## Roadmap
 
-```sh
-pnpm run typecheck
-pnpm run lint:ci
-pnpm run test:cov
-pnpm run verify
-```
+Revo is in active development. The public roadmap lives in GitHub Milestones and umbrella issues; this README only points to the current tracks.
+
+| Track | Start here |
+| --- | --- |
+| Default playbook stabilization | [Milestone #1](https://github.com/revisium/orchestrator/milestone/1), [umbrella #146](https://github.com/revisium/orchestrator/issues/146) |
+| GraphQL admin API v1 migration | [Milestone #4](https://github.com/revisium/orchestrator/milestone/4), [umbrella #167](https://github.com/revisium/orchestrator/issues/167) |
+| Execution profiles and runner/model binding | [Milestone #5](https://github.com/revisium/orchestrator/milestone/5), [umbrella #168](https://github.com/revisium/orchestrator/issues/168) |
+| Loop engineering layer | [Milestone #2](https://github.com/revisium/orchestrator/milestone/2), [umbrella #148](https://github.com/revisium/orchestrator/issues/148) |
+| Role and pipeline authoring | [Milestone #3](https://github.com/revisium/orchestrator/milestone/3), [umbrella #157](https://github.com/revisium/orchestrator/issues/157) |
+
+Use umbrella issues for initiative context and child issues for reviewable delivery slices. Work orders do not live in docs.
 
-The smoke scripts are guarded: they require a non-default `REVO_DATA_DIR`,
-`REVO_PORT`, `REVO_PG_PORT`, and `REVO_DBOS_DB`; GraphQL smoke paths also require
-`REVO_GRAPHQL_PORT`.
+## Local Development
+
+Use the `dev` profile when running a source checkout next to an installed package. The profile has isolated ports,
+data directory, and DBOS database.
 
 ```sh
-pnpm run smoke:control-plane
-pnpm run smoke:create-run
-pnpm run smoke:inspect-run
+pnpm install
+pnpm run revo -- start --profile dev
+pnpm run revo -- status --profile dev
+pnpm run revo -- doctor --profile dev
+pnpm run revo -- logs --profile dev
+pnpm run revo -- stop --profile dev
 ```
 
-### Live Run Observability Smoke
+| Knob | `default` | `dev` |
+| --- | --- | --- |
+| data dir | `~/.revisium-orchestrator` | `~/.revisium-orchestrator-dev` |
+| standalone HTTP / Postgres | `19222` / `15440` | `19622` / `15840` |
+| Revo GraphQL | `19223` | `19623` |
+| DBOS database | `dbos` | `dbos_dev` |
+
+Explicit environment variables override the profile: `REVO_DATA_DIR`, `REVO_PORT`, `REVO_PG_PORT`,
+`REVO_GRAPHQL_PORT`, and `REVO_DBOS_DB`.
+
+## Front Doors
 
-This smoke runs a real agent. It can call provider CLIs and incur cost. Use it
-only when that is intentional.
+`revo mcp` is the agent front door. It is a local stdio bridge to the daemon and exposes product-level tools for
+runs, gates, repository diagnostics, method discovery, and PR readiness.
 
 ```sh
-export REVO_SMOKE_REPO=/path/to/local/sandbox-repo
-pnpm run revo -- start --profile dev   # standalone + host daemon (serves GraphQL + MCP), ready
+codex mcp add --env REVO_PROFILE=dev revo-dev -- pnpm --dir /abs/path/to/orchestrator run revo -- mcp
+claude mcp add -e REVO_PROFILE=dev revo-dev -- pnpm --dir /abs/path/to/orchestrator run revo -- mcp
 ```
 
-Drive and observe a run through the daemon's front doors — there are no `run`/`serve` CLI commands.
-From an agent, use the MCP tools (`create_run`, `start_run`, then `get_agent_activity` /
-`get_agent_log`). From a UI or script, use the GraphQL front door the daemon already serves at
-`http://127.0.0.1:$REVO_GRAPHQL_PORT/graphql` — create a run:
-
-```graphql
-mutation Create($data: CreateRunInput!) {
-  createRun(data: $data) {
-    runId
-  }
-}
-```
+For the `dev` profile, GraphQL is available at `http://127.0.0.1:19623/graphql`.
 
-Then observe it over the same endpoint:
-
-```graphql
-query Activity($runId: ID!) {
-  runAgentActivity(runId: $runId) {
-    runId
-    aggregateStatus
-    latestOutputAt
-    attempts {
-      attemptId
-      runner
-      status
-      stdoutBytes
-      stderrBytes
-      artifactRef
-    }
-  }
-}
-
-query Log($data: GetAgentLogInput!) {
-  runAgentLog(data: $data) {
-    runId
-    attemptId
-    stream
-    offsetBytes
-    nextOffsetBytes
-    totalBytes
-    truncated
-    content
-  }
-}
-```
+## Verification
 
-For MCP, configure the MCP client to launch this checkout's local binary with the
-same environment. The MCP tools do not accept per-call profile arguments; the
-profile comes from the process environment.
-
-```json
-{
-  "mcpServers": {
-    "revo-dev": {
-      "command": "/path/to/agent-orchestrator/bin/revo.js",
-      "args": ["mcp"],
-      "env": {
-        "REVO_DATA_DIR": "/path/to/.revisium-orchestrator-dev",
-        "REVO_PORT": "19622",
-        "REVO_PG_PORT": "15840",
-        "REVO_GRAPHQL_PORT": "19623",
-        "REVO_DBOS_DB": "dbos_dev"
-      }
-    }
-  }
-}
+```sh
+pnpm run typecheck
+pnpm run lint:ci
+pnpm run test:cov
+pnpm run verify
 ```
 
-Useful MCP observability tools for the same run:
+Smoke and e2e scripts that start local daemons may need an unsandboxed terminal and isolated non-default ports.
 
-- `get_agent_activity`
-- `get_agent_attempts`
-- `get_agent_log`
-- `read_agent_output_events`
-- `tail_agent_log`
+## Documentation
 
-If running from a sandboxed automation environment, local server checks may fail
-with `listen EPERM` or a misleading `No free port found from <port>`. Re-run the
-daemon, GraphQL, and MCP smoke commands from a normal terminal or an approved
-unsandboxed execution context.
+| Start here | Purpose |
+| --- | --- |
+| [docs/README.md](./docs/README.md) | Documentation map and ownership rules |
+| [docs/vision.md](./docs/vision.md) | Product direction, glossary, and capability map |
+| [docs/architecture-overview.md](./docs/architecture-overview.md) | Runtime layers, invariants, and lifecycle |
+| [docs/developer-guide.md](./docs/developer-guide.md) | Source map and contributor onboarding |
+| [docs/specs/](./docs/specs/) | Exact product contracts |
+| [docs/adr/](./docs/adr/) | Durable architecture decisions |
+| [AGENTS.md](./AGENTS.md) | Repo-local instructions for coding agents |
 
 ## License
 
-See [LICENSE](./LICENSE).
+MIT - see [LICENSE](./LICENSE).

package/control-plane/default-playbook/catalog/pipelines.json

@@ -42,7 +42,8 @@
             "ci_changes",
             "fix",
             "wontfix",
-            "question"
+            "question",
+            "recheck"
           ]
         },
         "nodes": {
@@ -173,7 +174,10 @@
                 "node": "analyst",
                 "as": "plan"
               }
-            ]
+            ],
+            "produces": {
+              "name": "change"
+            }
           },
           "codeReview": {
             "id": "codeReview",
@@ -181,7 +185,19 @@
             "roleRef": "role:reviewer",
             "next": "codeReviewRouter",
             "onFailure": "abort",
-            "resultSchema": "schema:reviewVerdict"
+            "resultSchema": "schema:reviewVerdict",
+            "consumes": [
+              {
+                "node": "developer",
+                "as": "developerChange",
+                "staleOk": true
+              },
+              {
+                "node": "reworkDeveloper",
+                "as": "reworkChange",
+                "optional": true
+              }
+            ]
           },
           "codeReviewRouter": {
             "id": "codeReviewRouter",
@@ -255,7 +271,10 @@
             "resultSchema": "schema:change",
             "incrementCounters": [
               "codeReviewLoop"
-            ]
+            ],
+            "produces": {
+              "name": "change"
+            }
           },
           "integrator": {
             "id": "integrator",
@@ -273,14 +292,33 @@
               }
             ],
             "onFailure": "route",
-            "resultSchema": "schema:integration"
+            "resultSchema": "schema:integration",
+            "consumes": [
+              {
+                "node": "developer",
+                "as": "developerChange",
+                "staleOk": true
+              },
+              {
+                "node": "reworkDeveloper",
+                "as": "reworkChange",
+                "optional": true
+              },
+              {
+                "node": "ciRework",
+                "as": "ciChange",
+                "optional": true,
+                "staleOk": true
+              }
+            ]
           },
           "mergeGate": {
             "id": "mergeGate",
             "kind": "humanGate",
             "reason": "merge-review",
             "outcomes": [
-              "approved"
+              "approved",
+              "recheck"
             ],
             "branches": [
               {
@@ -290,15 +328,83 @@
                 },
                 "goto": "confirmMerge"
               },
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "recheck"
+                },
+                "goto": "mergeRecheck"
+              },
               {
                 "default": "blockedEnd"
               }
             ],
             "gatedArtifact": {
-              "node": "pollPr",
+              "node": "mergeReadiness",
               "as": "prFeedback"
             }
           },
+          "mergeRecheck": {
+            "id": "mergeRecheck",
+            "kind": "script",
+            "scriptRef": "script:pollPr",
+            "next": "mergeRecheckRouter",
+            "onFailure": "route",
+            "resultSchema": "schema:prFeedback",
+            "produces": {
+              "name": "prFeedback"
+            },
+            "catch": [
+              {
+                "onError": "revo.ScriptBlocked",
+                "goto": "blockedEnd"
+              },
+              {
+                "onError": "revo.ScriptFailed",
+                "goto": "failedEnd"
+              }
+            ]
+          },
+          "mergeRecheckRouter": {
+            "id": "mergeRecheckRouter",
+            "kind": "choice",
+            "branches": [
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "clean"
+                },
+                "goto": "blockedEnd"
+              },
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "review_changes"
+                },
+                "goto": "triage"
+              },
+              {
+                "when": {
+                  "op": "all",
+                  "of": [
+                    {
+                      "op": "verdict.eq",
+                      "value": "ci_changes"
+                    },
+                    {
+                      "op": "counter.lt",
+                      "scope": "ciLoop",
+                      "value": 3
+                    }
+                  ]
+                },
+                "goto": "ciRework"
+              },
+              {
+                "default": "blockedEnd"
+              }
+            ]
+          },
           "confirmMerge": {
             "id": "confirmMerge",
             "kind": "script",
@@ -315,7 +421,13 @@
               }
             ],
             "onFailure": "route",
-            "resultSchema": "schema:integration"
+            "resultSchema": "schema:integration",
+            "consumes": [
+              {
+                "node": "mergeReadiness",
+                "as": "mergeReadiness"
+              }
+            ]
           },
           "mergedEnd": {
             "id": "mergedEnd",
@@ -356,6 +468,67 @@
           "prRouter": {
             "id": "prRouter",
             "kind": "choice",
+            "branches": [
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "clean"
+                },
+                "goto": "mergeReadiness"
+              },
+              {
+                "when": {
+                  "op": "verdict.eq",
+                  "value": "review_changes"
+                },
+                "goto": "triage"
+              },
+              {
+                "when": {
+                  "op": "all",
+                  "of": [
+                    {
+                      "op": "verdict.eq",
+                      "value": "ci_changes"
+                    },
+                    {
+                      "op": "counter.lt",
+                      "scope": "ciLoop",
+                      "value": 3
+                    }
+                  ]
+                },
+                "goto": "ciRework"
+              },
+              {
+                "default": "blockedEnd"
+              }
+            ]
+          },
+          "mergeReadiness": {
+            "id": "mergeReadiness",
+            "kind": "script",
+            "scriptRef": "script:pollPr",
+            "next": "mergeReadinessRouter",
+            "onFailure": "route",
+            "resultSchema": "schema:prFeedback",
+            "produces": {
+              "name": "prFeedback"
+            },
+            "catch": [
+              {
+                "onError": "revo.ScriptBlocked",
+                "goto": "blockedEnd"
+              },
+              {
+                "onError": "revo.ScriptFailed",
+                "goto": "failedEnd"
+              }
+            ]
+          },
+          "mergeReadinessRouter": {
+            "id": "mergeReadinessRouter",
+            "kind": "choice",
             "branches": [
               {
                 "when": {
@@ -403,10 +576,25 @@
             "incrementCounters": [
               "ciLoop"
             ],
+            "produces": {
+              "name": "change"
+            },
             "consumes": [
               {
                 "node": "pollPr",
                 "as": "feedback"
+              },
+              {
+                "node": "mergeReadiness",
+                "as": "mergeFeedback",
+                "optional": true,
+                "staleOk": true
+              },
+              {
+                "node": "mergeRecheck",
+                "as": "recheckFeedback",
+                "optional": true,
+                "staleOk": true
               }
             ]
           },
@@ -429,6 +617,18 @@
               {
                 "node": "pollPr",
                 "as": "feedback"
+              },
+              {
+                "node": "mergeReadiness",
+                "as": "mergeFeedback",
+                "optional": true,
+                "staleOk": true
+              },
+              {
+                "node": "mergeRecheck",
+                "as": "recheckFeedback",
+                "optional": true,
+                "staleOk": true
               }
             ]
           },
@@ -520,6 +720,9 @@
             "incrementCounters": [
               "reviewLoop"
             ],
+            "produces": {
+              "name": "change"
+            },
             "consumes": [
               {
                 "node": "triage",
@@ -534,6 +737,12 @@
             "next": "respondThreads",
             "onFailure": "route",
             "resultSchema": "schema:integration",
+            "consumes": [
+              {
+                "node": "reviewRework",
+                "as": "reviewChange"
+              }
+            ],
             "catch": [
               {
                 "onError": "revo.ScriptBlocked",