feat: multi-agent foundation with recovery, quality gates, and migration compatibility

.github/pull_request_template.md

@@ -0,0 +1,35 @@
+## Summary
+- What changed:
+- Why this change is needed:
+
+## Scope
+- Type: feat / fix / refactor / docs / chore
+- Main area(s) touched:
+- Non-goals (what this PR intentionally does not solve):
+- Slice (if part of a larger effort):
+
+## Validation
+- `command` -> `result`
+- `command` -> `result`
+
+## Comprehensive Pre-PR Review
+- [ ] I ran the required pre-PR review gates locally.
+- [ ] I listed concrete validation evidence (commands + results).
+- [ ] I completed a comprehensive review and recorded findings severity.
+- [ ] I documented rollback trigger and rollback steps.
+- [ ] This PR is scoped to one concern (or one planned slice).
+
+## Findings
+- High:
+- Medium:
+- Low:
+
+## Risks
+- Behavior risk:
+- Compatibility risk:
+- Operational risk:
+
+## Rollback
+- Trigger:
+- Steps:
+- Verification after rollback:

.github/workflows/pre-pr-review-gate.yml

@@ -0,0 +1,34 @@
+name: pre-pr-review-gate
+
+on:
+  pull_request:
+    branches: [main]
+    types: [opened, edited, synchronize, reopened, ready_for_review]
+
+permissions:
+  contents: read
+  pull-requests: read
+
+jobs:
+  pre-pr-review-gate:
+    name: pre-pr-review-gate
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Ensure codex runtime artifacts are not tracked
+        run: |
+          set -euo pipefail
+          if git ls-files | rg -q '^\.codex-tasks/'; then
+            echo "ERROR: .codex-tasks artifacts must not be committed." >&2
+            git ls-files | rg '^\.codex-tasks/' >&2
+            exit 1
+          fi
+
+      - name: Validate PR comprehensive review checklist
+        env:
+          PR_BODY: ${{ github.event.pull_request.body }}
+        run: |
+          set -euo pipefail
+          bash ./scripts/ci/check_pr_review_gate.sh

.gitignore

@@ -31,6 +31,8 @@ collector_knowledge_base.json
 predictions_database.json
 prediction_report_*.md
 BUILD_LOG.md
+/.codex-tasks/
+/.longrun/
 
 # OS
 .DS_Store

CHANGELOG.md

@@ -5,6 +5,30 @@ All notable changes to OpenFang will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Multi-Agent Foundation Release Candidate
+- Finalized the multi-agent foundation release candidate handoff for `feat/multiagent-foundation-v1`, covering declarative workflow orchestration, durable workflow recovery, review/retry controls, audit/metrics hooks, session isolation, shadow routing, rollback controls, and OpenClaw migration compatibility.
+- Confirmed the upstream delivery plan is split into six reviewable slices with rollback notes and focused gates recorded in `.codex-tasks/openfang-multiagent-foundation/PROGRESS.md`.
+- Recorded the operator acceptance outcome: the two-user shadow drill passed with stable user-specific routing, no cross-session context bleed, successful shadow comparison capture, and rollback checklist execution inside the five-minute rollback window.
+
+### Handoff Checklist
+- [x] Operator guide is published in `docs/multi-agent-foundation.md` with shadow-run, rollout, and rollback instructions.
+- [x] Upstream PR slicing plan and submission checklist are captured in `.codex-tasks/openfang-multiagent-foundation/PROGRESS.md`.
+- [x] Two-user acceptance drill passed via focused gates for route specificity, session isolation, shadow comparison, and rollback controls.
+- [x] Release handoff notes are consolidated in `CHANGELOG.md` so the final row is documentation-only and does not introduce unrelated runtime refactors.
+
+### Known Risks
+- Multi-session isolation spans kernel, runtime, API, and workspace persistence; keep rollout gradual and monitor for session-scoped memory regressions when traffic increases.
+- Shadow and rollback controls are operator-facing guardrails; keep `stable_path` anchored to the last production route until each upstream slice is reviewed and landed.
+- OpenClaw migration compatibility covers historical identity/provider/bindings variants, so representative production exports should still be revalidated before promotion.
+
+### Operational Quality Gates
+- Added CI workflow `.github/workflows/pre-pr-review-gate.yml` to enforce comprehensive pre-PR checklist structure on `pull_request -> main`.
+- Added PR template `.github/pull_request_template.md` with mandatory sections: summary, scope, validation evidence, findings, risks, and rollback.
+- Added branch-protection automation script `scripts/ci/configure_branch_protection.sh` to apply required checks/review rules for `main` (default checks include pre-PR gate plus CI check/test/clippy/format).
+- Added operator docs: `docs/pr-quality-gates.md`; linked from `docs/README.md` and `CONTRIBUTING.md`.
+
 ## [0.1.0] - 2026-02-24
 
 ### Added

CONTRIBUTING.md

@@ -12,6 +12,7 @@ Thank you for your interest in contributing to OpenFang. This guide covers every
 - [How to Add a New Channel Adapter](#how-to-add-a-new-channel-adapter)
 - [How to Add a New Tool](#how-to-add-a-new-tool)
 - [Pull Request Process](#pull-request-process)
+- [PR Quality Gates](#pr-quality-gates)
 - [Code of Conduct](#code-of-conduct)
 
 ---
@@ -334,6 +335,22 @@ tools = ["my_tool"]
 
 7. **CI must pass**: All automated checks must be green before merge.
 
+8. **Review-first requirement**: Keep PR as Draft until comprehensive review findings are documented and blocking findings are resolved.
+
+### PR Quality Gates
+
+OpenFang uses a mandatory review-first workflow. Follow [`docs/pr-quality-gates.md`](docs/pr-quality-gates.md).
+
+Before changing a PR to Ready for review:
+
+1. Complete all required sections in `.github/pull_request_template.md`.
+2. Check all required items under `## Comprehensive Pre-PR Review`.
+3. Run local gate checks and include concrete validation evidence.
+4. Resolve all High findings and re-run focused regressions.
+5. Keep one concern per PR (or one planned slice).
+
+CI workflow `pre-pr-review-gate` validates the PR body structure and checklist state.
+
 ### Commit Messages
 
 Use clear, imperative-mood messages:

crates/openfang-api/src/channel_bridge.rs

@@ -1065,7 +1065,9 @@ pub async fn start_channel_bridge_with_config(
     // WhatsApp — supports Cloud API mode (access token) or Web/QR mode (gateway URL)
     if let Some(ref wa_config) = config.whatsapp {
         let cloud_token = read_token(&wa_config.access_token_env, "WhatsApp");
-        let gateway_url = std::env::var(&wa_config.gateway_url_env).ok().filter(|u| !u.is_empty());
+        let gateway_url = std::env::var(&wa_config.gateway_url_env)
+            .ok()
+            .filter(|u| !u.is_empty());
 
         if cloud_token.is_some() || gateway_url.is_some() {
             let token = cloud_token.unwrap_or_default();

crates/openfang-api/src/middleware.rs

@@ -106,6 +106,7 @@ pub async fn auth(
         || path == "/api/integrations/available"
         || path == "/api/integrations/health"
         || path == "/api/workflows"
+        || path == "/api/workflows/metrics"
         || path == "/api/logs/stream"
         || path.starts_with("/api/cron/")
         || path.starts_with("/api/providers/github-copilot/oauth/")