refactor: delegate review and PR gating to Pi plugins

CONTRIBUTING.md

@@ -16,7 +16,7 @@ Keep the ownership boundary strict:
 - Pi owns agent execution and session lifecycle.
 - `pi-subagents` owns child orchestration, worktrees, missions, schedules,
   resume, and external-agent runners.
-- ForgeFlow may add deterministic engineering invariants and acceptance gates
-  only when those policies are not already Pi primitives.
+- ForgeFlow may add deterministic engineering invariants only when the policy
+  is not already owned by Pi or an installed plugin.
 - Do not add a ForgeFlow database, generic provider router, scheduler,
   worktree manager, or durable execution engine.

README.md

@@ -1,65 +1,36 @@
 # ForgeFlow
 
-> Thin software-engineering governance for Pi Agent.
+> Thin software-engineering policy for Pi Agent.
 
-ForgeFlow is a Pi package, not a coding-agent runtime. Pi owns execution and
-`pi-subagents` owns delegation, child lifecycle, worktree isolation, missions,
-schedules, resume, background execution, and external-agent runners.
+ForgeFlow is a Pi package, not an agent runtime or workflow engine. Pi and its
+plugins own execution. ForgeFlow keeps only policy that is useful across those
+plugins.
 
-ForgeFlow adds only engineering policy that is not already a Pi primitive.
+## What ForgeFlow owns
 
-## Architecture
+- stable logical model roles:
+  `forgeflow/planner`, `worker`, `reviewer`, `scout`, and `oracle`;
+- deterministic engineering-invariant preflight;
+- the one-writer-per-worktree rule;
+- policy reminders that bind delivery evidence to the current candidate.
 
-```text
-Pi Agent
-  |
-  +-- pi-subagents
-  |    +-- worker / reviewer / scout / oracle
-  |    +-- worktrees / missions / schedules / resume
-  |    +-- external-cli / external-job agents
-  |
-  +-- ForgeFlow
-       +-- stable logical model roles via Pi virtual models
-       +-- deterministic invariant preflight
-       +-- one-writer policy
-       +-- independent review workflow
-       +-- exact-head GitHub acceptance
-```
-
-The governing rule is:
-
-> Agent success is evidence, not engineering acceptance.
-
-ForgeFlow deliberately does **not** implement sessions, provider/channel routing,
-generic agent execution, durable workflow state, a second worktree manager, or
-a second scheduler. It can map stable engineering roles such as `forgeflow/worker`
-to physical Pi models, while credentials, endpoints, channel weights, quotas, and
-transport remain owned by Pi/provider infrastructure.
-
-See [`docs/model-policy.md`](./docs/model-policy.md) for the logical-model policy and provider boundary.
-
-## Workflows
-
-### `forgeflow.review`
-
-Runs a fresh Pi reviewer on the stable `forgeflow/reviewer` virtual model,
-persists the full report under `.pi/subagents/`, and uses a Pi typed gate to
-validate the reviewer's canonical final merge verdict. Malformed or missing
-verdicts fail closed.
-
-### `forgeflow.accept`
+## What ForgeFlow does not own
 
-Binds final acceptance to one exact committed candidate:
+Pi and installed plugins own child execution, review loops, acceptance gates,
+worktrees, missions, schedules, resume, background jobs, external-agent runners,
+and pull-request gating.
 
-1. the local worktree must be clean and at the requested HEAD;
-2. a fresh independent reviewer must return a clean typed verdict;
-3. the local HEAD must remain unchanged during review;
-4. the authoritative open PR must still target the expected base and exact HEAD;
-5. every configured required GitHub check must have a successful terminal result.
+Use `pi-subagents` for delegation, reviewers, and runtime acceptance evidence.
+When `pi-gauntlet` is installed, use its `gatekeep-pr` skill for exact-head PR
+verification and merge safety. ForgeFlow deliberately does not wrap or duplicate
+those surfaces.
 
-A new push changes the candidate and invalidates prior acceptance evidence.
+Provider infrastructure remains below Pi model selection. ForgeFlow logical roles
+may resolve to physical models, while endpoint selection, credentials, channel
+health, weights, quotas, and transport belong to the provider layer.
 
-See [`docs/architecture.md`](./docs/architecture.md) for the ownership boundary.
+See [`docs/model-policy.md`](./docs/model-policy.md) for logical-model policy and
+[`docs/architecture.md`](./docs/architecture.md) for the ownership boundary.
 
 ## Development
 

docs/architecture.md

@@ -1,83 +1,82 @@
 # ForgeFlow architecture
 
-ForgeFlow is a thin governance package for Pi Agent.
+ForgeFlow is a thin policy package for Pi Agent.
 
 ## Ownership
 
-### Pi / pi-subagents own
+### Pi and installed plugins own
 
-- physical model and provider execution;
-- virtual-model dispatch mechanics and subagent model resolution;
-- parent and child sessions;
-- subagent dispatch and lifecycle;
-- worktree isolation;
-- missions, schedules, background work, resume, and retained children;
-- external CLI/job agent runners;
-- workflow receipts and runtime artifacts.
+- physical model/provider execution and virtual-model dispatch mechanics;
+- parent/child sessions and subagent lifecycle;
+- worktree isolation, missions, schedules, background work, resume, and retained children;
+- external CLI/job runners;
+- reviewer execution, review loops, and runtime acceptance evidence;
+- pull-request verification, CI evidence collection, freshness checks, and merge operations.
+
+`pi-subagents` is the primary child/runtime primitive. When installed,
+`pi-gauntlet` provides higher-level engineering workflows such as `gatekeep-pr`.
+ForgeFlow does not wrap those capabilities in a second workflow layer.
 
 ### ForgeFlow owns
 
-- stable engineering model roles (`forgeflow/planner`, `worker`, `reviewer`, `scout`, `oracle`) and their thin operator-controlled role policy;
+- stable engineering model roles (`forgeflow/planner`, `worker`, `reviewer`, `scout`, `oracle`);
 - a deterministic engineering-invariant preflight;
 - the one-writer-per-worktree governance rule;
-- the trusted `forgeflow.review` resource;
-- the trusted `forgeflow.accept` exact-head acceptance resource;
-- deterministic parsing of reviewer verdicts and GitHub check evidence.
+- policy text requiring evidence to remain bound to the current candidate.
 
-If a new feature needs generic execution, scheduling, workflow state, provider/channel routing, worktrees,
-or resume, it belongs in Pi/pi-subagents or the provider layer rather than ForgeFlow. ForgeFlow may select a physical model for an engineering role through Pi's native virtual-model primitive, but it must not own API transport, credentials, channel weights, quota routing, or a second model runtime.
+If a feature needs generic execution, review orchestration, PR acceptance,
+scheduling, durable workflow state, provider/channel routing, worktrees, or resume,
+it belongs in Pi, an existing plugin, or the provider layer rather than ForgeFlow.
 
 ## Model policy boundary
 
-ForgeFlow registers stable logical roles as Pi virtual models. Their physical model mapping is read from operator policy rather than hard-coded into workflows or subagent definitions. For native pi-subagents children, ForgeFlow registers its own extension as a required child extension so those virtual roles are present even though local foreground children intentionally skip parent ambient-extension discovery. New user/direct requests resolve the current mapping, while continuation/retry requests stay on the physical model already handling the turn to preserve prompt-cache and reasoning-signature continuity.
+ForgeFlow registers stable logical roles as Pi virtual models. Their physical model
+mapping is read from operator policy rather than hard-coded into workflows or agent
+definitions.
+
+For native pi-subagents children, ForgeFlow registers its own extension as a
+required child extension. Local foreground children intentionally skip parent
+ambient-extension discovery, so this keeps the `forgeflow/*` roles available in
+foreground, detached, nested, and recovery child sessions without hard-coding an
+installation path in operator profile settings.
+
+New user/direct requests resolve the current role mapping. Continuation/retry
+requests stay on the physical model already handling the turn to preserve cache and
+reasoning-signature continuity.
 
-Project-local `.pi/forgeflow-models.json` is considered only when Pi reports the project trusted. User-level policy under `~/.pi/forgeflow-models.json` remains available for untrusted projects. `FORGEFLOW_MODEL_POLICY` is an explicit operator override.
+Project-local `.pi/forgeflow-models.json` is considered only when Pi reports the
+project trusted. User-level policy under `~/.pi/forgeflow-models.json` remains
+available for untrusted projects. `FORGEFLOW_MODEL_POLICY` is an explicit operator
+override.
 
-Provider gateways such as LiteLLM/New API/Bifrost sit below this boundary: ForgeFlow chooses the physical model; the provider plane chooses endpoint/channel/key for that already-selected model. This avoids double semantic routing.
+Provider gateways such as LiteLLM sit below this boundary: ForgeFlow chooses a
+logical role and Pi resolves its physical model; the provider plane chooses the
+endpoint/channel/key for that already-selected physical model.
 
 See `docs/model-policy.md` for the v1 schema and role mapping.
 
 ## Invariant preflight
 
-`extension/invariants.js` is the retained learning layer. It contains a small
-stable catalog covering owner validation, product time, identity ownership,
+`extension/invariants.js` is the retained engineering-policy layer. It contains a
+small stable catalog covering owner validation, product time, identity ownership,
 lifecycle/tombstones, retry/idempotency, path parity, preflight-before-mutation,
 stable ordering, host-owned facts, and single-truth cutovers.
 
 The preflight is deterministic and adds no model call or durable workflow state.
 
-## Independent review
-
-`forgeflow.review` launches the builtin Pi reviewer agent with fresh context and
-explicitly selects the stable `forgeflow/reviewer` virtual model. The reviewer is
-read-only. Its full report is persisted to an absolute path under `.pi/subagents/`.
-
-A Pi typed gate executes `scripts/review-verdict.mjs` against that same report.
-Only Pi's canonical merge-verdict forms are accepted:
-
-- `Merge verdict: BLOCK|OK|OK with notes`
-- the builtin reviewer's Markdown-list form of the same line.
-
-Anything else fails closed.
-
-## Exact-head acceptance
-
-`forgeflow.accept` performs four independent gates in order:
+## Review and delivery
 
-1. **HEAD before review** — the worktree is clean and equals `expectedHead`.
-2. **Fresh review** — the Pi reviewer running as `forgeflow/reviewer` must return a clean typed verdict.
-3. **HEAD after review** — review must not have changed the candidate.
-4. **GitHub exact-head** — the PR is open, targets the expected base, still
-   points at `expectedHead`, and every configured required check resolves to
-   the newest unambiguous terminal `success`.
+ForgeFlow does not implement a reviewer runtime or PR acceptance workflow.
 
-The reviewer evaluates code/contracts/repository-local evidence. Live GitHub CI
-state is deliberately owned by the final host gate, avoiding a circular
-requirement for a read-only reviewer to prove external check-run state.
+Use the reviewer and acceptance primitives already supplied by `pi-subagents`.
+For GitHub PR delivery, `pi-gauntlet`'s `gatekeep-pr` skill (when installed)
+already handles exact-head CI evidence, head freshness, review, compare-and-swap,
+and head-matched merge execution. Adding a second ForgeFlow implementation would
+create two sources of truth for the same gate.
 
 ## Retired architecture
 
-The former Python/LangGraph/Open SWE control plane, its provider routing,
-attempt ledger, custom agent wrappers, Docker sandbox deployment, supervisors,
-and GCP systemd units were removed during the Pi-native cutover. Git history is
-the audit record for that retired implementation.
+The former Python/LangGraph/Open SWE control plane, provider routing, attempt ledger,
+custom agent wrappers, Docker sandbox deployment, supervisors, and GCP systemd units
+were removed during the Pi-native cutover. Git history is the audit record for that
+retired implementation.

docs/model-policy.md

@@ -45,7 +45,7 @@ The pinned `pi-subagents@0.75.0` includes the child-runtime fixes required for P
 }
 ```
 
-The parent Pi session can select `forgeflow/planner` when the parent is acting as the planning/orchestration role. ForgeFlow's trusted `forgeflow.review` and `forgeflow.accept` workflows explicitly request `forgeflow/reviewer`, so the workflow owns the stable reviewer role while operator policy remains free to change the physical reviewer model without editing workflow code.
+The parent Pi session can select `forgeflow/planner` when acting as the planning/orchestration role. Reviewer and acceptance plugins should select `forgeflow/reviewer` when they need the stable reviewer role; operator policy remains free to change the physical reviewer model without editing plugin workflows or agent definitions.
 
 `pi-subagents@0.75.0` contains the upstream child-runtime fixes for queued virtual-model registration and logical-selection verification (#2636 and #2638). ForgeFlow also registers its own extension as a required native-child extension for each Pi session, because local foreground children intentionally do not load the parent's ambient extensions. This makes the `forgeflow/*` virtual models available in foreground, detached, nested, and recovery child sessions without hard-coding an installation path in operator profile settings. External CLI runners remain excluded by pi-subagents. ForgeFlow therefore does not carry a virtual-child compatibility shim.