B4: ship bridge packaging and smoke docs (#148)

Co-authored-by: Sami Rusani <sr@samirusani>

Author: samrusani

BUILD_REPORT.md

@@ -1,68 +1,66 @@
 # BUILD_REPORT
 
 ## sprint objective
-Implement Bridge Sprint 3 (`B3`) review queue + explainability scope:
-- ship `alice_review_queue`
-- ship `alice_review_apply`
-- support review actions (`approve`, `reject`, `edit-and-approve`, `supersede-existing`)
-- expose explanation/provenance rationale in review surfaces
-- verify deterministic recall/resume effects after approved review actions
+Deliver Bridge Sprint 4 (`B4`) closeout scope only: package and document the shipped bridge phase for external operators, publish recommended/fallback Hermes config guidance, strengthen bridge smoke validation evidence, and provide a one-command local demo path.
 
 ## completed work
-- Added MCP tool surface `alice_review_queue` with deterministic queue/detail behavior.
-- Added MCP tool surface `alice_review_apply` with B3 action vocabulary mapped to continuity correction semantics:
-  - `approve` -> `confirm`
-  - `edit-and-approve` -> `edit`
-  - `reject` -> `delete`
-  - `supersede-existing` -> `supersede`
-- Kept `alice_memory_review` and `alice_memory_correct` as compatibility aliases.
-- Extended continuity review serialization to include shared explanation records on review objects.
-- Added deterministic `proposal_rationale` to continuity explanation output.
-- Ensured explanation chain remains shared across review, recall, and resume paths.
-- Updated B3-scoped integration docs for MCP and Hermes memory-provider guidance.
-- Updated architecture status markers so B3 review surfaces are marked implemented and only B4 follow-up remains planned.
-- Updated control-doc truth checker markers to B3 active-sprint truth.
-- Updated B3 review evidence report (`REVIEW_REPORT.md`).
-- Added/updated sprint-owned tests for:
-  - MCP tool surface and B3 names
-  - action alias mapping and deterministic correction semantics
-  - review queue explainability presence
-  - recall exclusion after reject and recall/resume updates after supersede
+- Published canonical B4 operator guide: `docs/integrations/hermes-bridge-operator-guide.md`.
+- Published operator decision note: `docs/integrations/hermes-provider-plus-mcp-why.md`.
+- Published concrete Hermes `config.yaml` examples:
+  - recommended path: `docs/integrations/examples/hermes-config.provider-plus-mcp.yaml`
+  - fallback path: `docs/integrations/examples/hermes-config.mcp-only.yaml`
+- Updated in-scope integration docs (`README.md`, `hermes.md`, `hermes-memory-provider.md`, `mcp.md`, `hermes-skill-pack.md`) to align on:
+  - recommended path: provider plus MCP
+  - fallback path: MCP-only
+  - migration path from MCP-only to provider plus MCP
+  - one-command demo command: `./.venv/bin/python scripts/run_hermes_bridge_demo.py`
+- Strengthened `scripts/run_hermes_mcp_smoke.py` to validate bridge flow beyond recall/resume/open-loops by also validating B2/B3 capture and review operations (`alice_capture_candidates`, `alice_commit_captures`, `alice_review_queue`, `alice_review_apply`).
+- Added one-command demo helper: `scripts/run_hermes_bridge_demo.py`.
+- Added sprint-owned validation coverage for the demo helper: `tests/unit/test_hermes_bridge_demo.py`.
+- Updated `scripts/check_control_doc_truth.py` required markers to B4-active truth so the required verifier aligns with the active sprint packet.
+- Updated `REVIEW_REPORT.md` to grade against B4-specific acceptance criteria and evidence.
 
 ## incomplete work
-- None in B3 sprint scope.
+- None within B4 sprint scope.
 
 ## files changed
-- `ARCHITECTURE.md`
 - `PRODUCT_BRIEF.md`
 - `README.md`
 - `ROADMAP.md`
-- `apps/api/src/alicebot_api/continuity_explainability.py`
-- `apps/api/src/alicebot_api/continuity_review.py`
-- `apps/api/src/alicebot_api/contracts.py`
-- `apps/api/src/alicebot_api/mcp_tools.py`
-- `docs/integrations/mcp.md`
 - `docs/integrations/hermes-memory-provider.md`
+- `docs/integrations/hermes-skill-pack.md`
+- `docs/integrations/hermes.md`
+- `docs/integrations/mcp.md`
+- `docs/integrations/hermes-bridge-operator-guide.md`
+- `docs/integrations/hermes-provider-plus-mcp-why.md`
+- `docs/integrations/examples/hermes-config.provider-plus-mcp.yaml`
+- `docs/integrations/examples/hermes-config.mcp-only.yaml`
+- `scripts/run_hermes_mcp_smoke.py`
+- `scripts/run_hermes_bridge_demo.py`
 - `scripts/check_control_doc_truth.py`
-- `tests/unit/test_continuity_review.py`
-- `tests/unit/test_mcp.py`
-- `tests/integration/test_mcp_server.py`
+- `tests/unit/test_hermes_bridge_demo.py`
 - `REVIEW_REPORT.md`
 - `BUILD_REPORT.md`
 
 ## tests run
 - `python3 scripts/check_control_doc_truth.py`
   - Result: PASS
 - `./.venv/bin/python -m pytest tests/unit tests/integration -q`
-  - Result: `1189 passed in 196.98s (0:03:16)` (latest re-run)
+  - Result: `1191 passed in 187.48s (0:03:07)`
 - `./.venv/bin/python scripts/run_hermes_memory_provider_smoke.py`
   - Result: PASS
-  - Evidence summary: single-external-provider enforcement message emitted; structural payload reports `single_external_enforced=true` and `bridge_status.ready=true`.
-  - Local filesystem-specific path fields from script output were intentionally omitted for identifier hygiene.
+  - Evidence summary: `bridge_status.ready=true`, `single_external_enforced=true`, provider registered.
+- `./.venv/bin/python scripts/run_hermes_mcp_smoke.py`
+  - Result: PASS
+  - Evidence summary: required Hermes MCP tools registered, `recall_items=2`, `open_loop_count=1`, `capture_candidate_count=2`, `capture_auto_saved_count=1`, `capture_review_queued_count=1`, `review_apply_resolved_action=confirm`.
+- `./.venv/bin/python scripts/run_hermes_bridge_demo.py`
+  - Result: PASS
+  - Evidence summary: `status=pass`, `recommended_path=provider_plus_mcp`, `fallback_path=mcp_only`.
 
 ## blockers/issues
-- No functional blockers.
-- No outstanding evidence or documentation blockers after alignment updates.
+- Initial run of `scripts/run_hermes_mcp_smoke.py` failed due local database schema lag and sandbox DB access restriction.
+- Resolved by applying local migrations (`./scripts/migrate.sh`) and rerunning smoke commands with local DB access available.
+- No remaining blockers.
 
 ## recommended next step
-Proceed to Bridge Sprint 4 (`B4`) packaging/docs/smoke closeout using the now-shipped B3 review queue/apply surfaces as baseline.
+Request B4 review against this evidence and, if approved, proceed with the single sprint PR for squash merge closeout.

PRODUCT_BRIEF.md

@@ -70,7 +70,7 @@ Review-required:
 - low-confidence extractions
 
 ## Active Sprint Status
-Bridge Sprint 3 (`B3`) is now the active execution sprint. It is limited to review queue and explainability work on top of the shipped Hermes provider surface plus the `B1` and `B2` bridge foundations.
+Bridge Sprint 4 (`B4`) is now the active execution sprint. It is limited to packaging, docs, config examples, smoke validation, and local-demo closeout on top of the shipped `B1` through `B3` bridge foundations.
 
 ## Known Gaps To Resolve Before Build
 - Candidate scoring rubric and confidence calibration method are not specified.

README.md

@@ -41,7 +41,8 @@ Phase 11 is complete and shipped:
 - A bridge phase is now active: Hermes Auto-Capture
 - `B1` Hermes Provider Contract Foundation is shipped
 - `B2` Auto-Capture Pipeline is shipped
-- `B3` Review Queue + Explainability is the active sprint
+- `B3` Review Queue + Explainability is shipped
+- `B4` Packaging, Docs, and Smoke Validation is the active sprint
 - Historical planning and control docs: [docs/archive/planning/2026-04-08-context-compaction/README.md](docs/archive/planning/2026-04-08-context-compaction/README.md)
 
 ## Why Alice exists
@@ -217,20 +218,31 @@ This makes it straightforward to plug Alice into MCP-capable assistants and deve
 
 See:
 
+- [docs/integrations/hermes-bridge-operator-guide.md](docs/integrations/hermes-bridge-operator-guide.md)
+- [docs/integrations/hermes-provider-plus-mcp-why.md](docs/integrations/hermes-provider-plus-mcp-why.md)
 - [docs/integrations/mcp.md](docs/integrations/mcp.md)
 - [docs/integrations/hermes.md](docs/integrations/hermes.md)
 - [docs/integrations/hermes-memory-provider.md](docs/integrations/hermes-memory-provider.md)
 - [docs/integrations/hermes-skill-pack.md](docs/integrations/hermes-skill-pack.md)
 - [docs/integrations/phase11-local-provider-adapters.md](docs/integrations/phase11-local-provider-adapters.md)
 - [docs/integrations/phase11-azure-autogen.md](docs/integrations/phase11-azure-autogen.md)
 
-Hermes runtime smoke test:
+Recommended Hermes architecture is provider plus MCP, with MCP-only as a fallback.
+
+One-command Hermes bridge demo:
+
+```bash
+./.venv/bin/python scripts/run_hermes_bridge_demo.py
+```
+
+Hermes runtime smoke tests:
 
 ```bash
-./scripts/run_hermes_mcp_smoke.py
+./.venv/bin/python scripts/run_hermes_memory_provider_smoke.py
+./.venv/bin/python scripts/run_hermes_mcp_smoke.py
 ```
 
-If you use Hermes, Alice supports three integration modes: MCP, skill pack, and a first-class external memory provider for turn prefetch plus recall, resumption, and open-loop tools.
+If you use Hermes, run provider plus MCP as the recommended mode, add the skill pack for policy guidance, and keep MCP-only available as fallback.
 
 ## OpenClaw and imported workflows
 

REVIEW_REPORT.md

@@ -4,43 +4,54 @@
 PASS
 
 ## criteria met
-- `alice_review_queue` is implemented and exposed on MCP.
-- `alice_review_apply` is implemented and exposed on MCP.
-- Required B3 review actions are supported through shipped surface semantics:
-  - `approve` -> `confirm`
-  - `edit-and-approve` -> `edit`
-  - `reject` -> `delete`
-  - `supersede-existing` -> `supersede`
-- Review payloads now include explainability/provenance chain data (`source_facts`, `evidence_segments`, `trust`, `supersession_notes`, `proposal_rationale`).
-- Approved review actions deterministically affect later recall/resume behavior (validated in integration flow using supersede).
-- Rejected review items are not treated as accepted continuity state (validated by recall exclusion after reject).
-- No local identifiers (local usernames/absolute machine paths) were found in changed code/docs/reports.
+- External-operator Hermes bridge documentation is complete and B4-specific via:
+  - `docs/integrations/hermes-bridge-operator-guide.md`
+  - `docs/integrations/hermes-provider-plus-mcp-why.md`
+- Provider-plus-MCP recommended architecture is documented clearly.
+- MCP-only fallback path is documented clearly.
+- MCP-only to provider-plus-MCP migration guidance is documented.
+- Example Hermes configs are present for both paths:
+  - `docs/integrations/examples/hermes-config.provider-plus-mcp.yaml`
+  - `docs/integrations/examples/hermes-config.mcp-only.yaml`
+- One-command local demo path is present and documented:
+  - `./.venv/bin/python scripts/run_hermes_bridge_demo.py`
+- Smoke validation for the shipped bridge path passes:
+  - provider smoke PASS
+  - MCP smoke PASS (including B2/B3 capture/review flow checks)
+  - bridge demo PASS
+- `BUILD_REPORT.md` now lists the exact sprint-owned changed files, including the previously omitted `PRODUCT_BRIEF.md` and `ROADMAP.md`.
+- No local identifiers (local machine paths/usernames) were found in changed docs/scripts/reports.
+- No B4 changes reopen B1/B2/B3 implementation scope or imply post-bridge scope.
 
 ## criteria missed
-- None functionally against B3 acceptance criteria.
+- None.
 
 ## quality issues
-- No blocking quality issues found in B3 scope.
+- No blocking quality issues found in B4 scope.
 
 ## regression risks
-- Low: MCP surface additions are additive, and targeted + full unit/integration suites pass.
-- Moderate-low: review queue objects now include full explanation payloads, increasing response size; monitor MCP client assumptions on payload size/shape.
+- Low: changes are primarily docs/config examples plus additive smoke/demo orchestration.
+- Moderate-low: expanded MCP smoke depends on local schema being migrated before execution.
 
 ## docs issues
-- None blocking. Architecture and build evidence alignment issues are fixed.
+- None blocking.
 
 ## should anything be added to RULES.md?
 - No required change.
 
 ## should anything update ARCHITECTURE.md?
-- No additional architecture changes required for B3.
+- No required architecture update for B4 closeout.
 
 ## recommended next action
-1. Approve B3 for merge.
-2. Start B4 packaging/docs/demo closeout.
+1. Proceed with sprint PR finalization and squash-merge flow.
+2. Keep the bridge demo command in release notes/operator handoff for external adopters.
 
 ## verification evidence checked
 - `python3 scripts/check_control_doc_truth.py` -> PASS
-- `./.venv/bin/python -m pytest tests/unit/test_continuity_review.py tests/unit/test_mcp.py tests/integration/test_mcp_server.py -q` -> `13 passed`
-- `./.venv/bin/python -m pytest tests/unit tests/integration -q` -> `1189 passed in 196.98s (0:03:16)`
+- `./.venv/bin/python -m pytest tests/unit tests/integration -q` -> `1191 passed in 187.48s (0:03:07)`
 - `./.venv/bin/python scripts/run_hermes_memory_provider_smoke.py` -> PASS
+- `./.venv/bin/python scripts/run_hermes_mcp_smoke.py` -> PASS
+- `./.venv/bin/python scripts/run_hermes_bridge_demo.py` -> PASS
+- Recommended path documented: `provider_plus_mcp`
+- Fallback path documented: `mcp_only`
+- Demo command documented: `./.venv/bin/python scripts/run_hermes_bridge_demo.py`

ROADMAP.md

@@ -8,8 +8,8 @@
 Phase 11 remains baseline truth and is not future scope.
 
 ## Active Planning Status
-- Bridge Sprint 3 (`B3`) is the active execution sprint.
-- The remaining bridge-phase milestones are planned but not yet promoted.
+- Bridge Sprint 4 (`B4`) is the active execution sprint.
+- `B4` is the final planned bridge-phase sprint.
 
 ## Bridge Phase: Hermes Auto-Capture (Planned)
 

docs/integrations/examples/hermes-config.mcp-only.yaml

@@ -0,0 +1,22 @@
+# Fallback deployment shape when provider install is not available.
+# This keeps explicit MCP workflows, but no provider prefetch/capture hooks.
+memory:
+  provider: builtin
+
+mcp_servers:
+  alice_core:
+    command: "/path/to/alicebot/.venv/bin/python"
+    args: ["-m", "alicebot_api.mcp_server"]
+    env:
+      DATABASE_URL: "postgresql://alicebot_app:alicebot_app@localhost:5432/alicebot"
+      ALICEBOT_AUTH_USER_ID: "00000000-0000-0000-0000-000000000001"
+      PYTHONPATH: "/path/to/alicebot/apps/api/src:/path/to/alicebot/workers"
+    tools:
+      include:
+        - alice_recall
+        - alice_resume
+        - alice_open_loops
+        - alice_review_queue
+        - alice_review_apply
+      resources: false
+      prompts: false

docs/integrations/examples/hermes-config.provider-plus-mcp.yaml

@@ -0,0 +1,24 @@
+# Recommended bridge deployment shape.
+# Keep the Alice memory provider active for always-on prefetch/capture,
+# and keep Alice MCP attached for explicit deep workflows.
+memory:
+  provider: alice
+
+mcp_servers:
+  alice_core:
+    command: "/path/to/alicebot/.venv/bin/python"
+    args: ["-m", "alicebot_api.mcp_server"]
+    env:
+      DATABASE_URL: "postgresql://alicebot_app:alicebot_app@localhost:5432/alicebot"
+      ALICEBOT_AUTH_USER_ID: "00000000-0000-0000-0000-000000000001"
+      PYTHONPATH: "/path/to/alicebot/apps/api/src:/path/to/alicebot/workers"
+    tools:
+      include:
+        - alice_recall
+        - alice_resume
+        - alice_open_loops
+        - alice_review_queue
+        - alice_review_apply
+        - alice_explain
+      resources: false
+      prompts: false

docs/integrations/hermes-bridge-operator-guide.md

@@ -0,0 +1,101 @@
+# Hermes Bridge Operator Guide (B4)
+
+This is the canonical operator guide for the shipped bridge phase.
+
+Recommended deployment shape: **provider plus MCP**.
+
+- Provider handles always-on prefetch and post-turn lifecycle hooks.
+- MCP handles explicit deep workflows (review, correction, explainability, targeted recall).
+
+Use MCP-only as a fallback when provider install is temporarily blocked.
+
+## Integration Modes
+
+| Mode | Status | When to use | Tradeoff |
+|---|---|---|---|
+| Provider + MCP | Recommended | Default production/dev setup | Full bridge behavior with explicit deep actions |
+| MCP-only | Fallback | Provider plugin cannot be installed yet | No provider lifecycle hooks or automatic prefetch/capture |
+
+## Config Examples (`~/.hermes/config.yaml`)
+
+- Recommended mode: `docs/integrations/examples/hermes-config.provider-plus-mcp.yaml`
+- Fallback mode: `docs/integrations/examples/hermes-config.mcp-only.yaml`
+
+### Recommended snippet (provider + MCP)
+
+```yaml
+memory:
+  provider: alice
+
+mcp_servers:
+  alice_core:
+    command: "/path/to/alicebot/.venv/bin/python"
+    args: ["-m", "alicebot_api.mcp_server"]
+```
+
+### Fallback snippet (MCP-only)
+
+```yaml
+memory:
+  provider: builtin
+
+mcp_servers:
+  alice_core:
+    command: "/path/to/alicebot/.venv/bin/python"
+    args: ["-m", "alicebot_api.mcp_server"]
+```
+
+## One-Command Local Demo
+
+Run the bridge demo command from this repository:
+
+```bash
+./.venv/bin/python scripts/run_hermes_bridge_demo.py
+```
+
+Expected result:
+
+- `status` is `pass`
+- `recommended_path` is `provider_plus_mcp`
+- `fallback_path` is `mcp_only`
+- provider smoke and MCP smoke steps both return `0`
+
+## Validation Commands
+
+Run these directly when you need independent evidence:
+
+```bash
+./.venv/bin/python scripts/run_hermes_memory_provider_smoke.py
+./.venv/bin/python scripts/run_hermes_mcp_smoke.py
+```
+
+## MCP-Only to Provider+MCP Migration
+
+1. Keep your existing MCP block unchanged.
+2. Install the Alice provider plugin:
+
+```bash
+./scripts/install_hermes_alice_memory_provider.py
+```
+
+3. Run Hermes memory setup and select `alice`:
+
+```bash
+hermes memory setup
+```
+
+4. Set `memory.provider` to `alice` in `config.yaml`.
+5. Re-run the one-command demo:
+
+```bash
+./.venv/bin/python scripts/run_hermes_bridge_demo.py
+```
+
+6. Keep MCP enabled for explicit review/correction/explain workflows.
+
+## Related Docs
+
+- `docs/integrations/hermes-provider-plus-mcp-why.md`
+- `docs/integrations/hermes-memory-provider.md`
+- `docs/integrations/hermes.md`
+- `docs/integrations/hermes-skill-pack.md`