feat: add dual-domain program exit demo and production handoff

[ctrl-is]

Summary

Completes DS-W8, the Primer Core program-exit gate, by assembling the existing Knowledge Graph, Learning Data, Didactic Skills, and evaluation work into one dual-domain demonstration and production handoff.

The new exit demo runs both education and coop-finance through the same orchestration engine, exercises the typed AG-UI streaming surface, demonstrates cross-session memory write-back, and then runs the existing swap-parity and transition-metric harness.

Changes

Dual-Domain Exit Demo

Added demos/demo_dual_domain.py as the one-command program finale.

For both education and coop-finance, the demo:

• Uses the shared EngagementOrchestrator.
• Runs the registered domain engagement through run_engagement_streaming.
• Verifies that the streaming surface emits typed AGUIEvent instances.
• Demonstrates engagement write-back through MemoryCore.ingest -> FileMemoryStore.
• Creates a second session over the same memory store and verifies that assemble_working_memory surfaces the first session's persisted outcome.
• Reuses the existing evaluation harness for transition metrics and run_swap_parity.
• Runs the eval test suite in a bounded subprocess with timeout=.
• Exits non-zero if any domain leg or evaluation gate fails.

Education Memory Demo

Refactored demos/demo_education.py so its memory round-trip path can be reused by the dual-domain demo while preserving the existing education demo entrypoint and DEMO SUCCESS output contract.

Production Handoff

Added docs/proposal/handoff.md covering:

• Reference adapters -> production service mapping.
• WorkflowCliRunner, PgVectorKnowledgeBase, and FileMemoryStore.
• Streaming write-back contract.
• Hook failure policy.
• Typed KnowledgeBaseUnavailable degradation behavior.
• LD-W7 memory-store conformance expectations.
• Known production risks and follow-on work.
• Commands for the full suite, primer-eval, eval-marked tests, and all three demos.
• Combined proposal document set and program-exit checklist.

Program Exit Results

Full Suite

uv run pytest -m 'not manual' -q

• 261 passed
• 1 skipped

Eval Marker

uv run pytest -m eval -v

• 4 passed
• 1 skipped

Primer Eval

uv run primer-eval

• 7/7 cases passed
• declarative_orchestration ✅
• typed_models ✅
• port_conformance ✅
• protocol_compliance ✅
• stateless_agents ✅
• run_swap_parity ✅

Knowledge-Base Domain Swap Demo

uv run python demos/kb_domain_swap.py

• Retrieval wiring: PASS
• Engine module parity: PASS
• Zero engine branching: PASS

Education Memory Demo

uv run python demos/demo_education.py

• Session 1 write-back persisted through FileMemoryStore
• Session 2 working memory reproduced the persisted outcome
• DEMO SUCCESS

Dual-Domain Exit Demo

uv run python demos/demo_dual_domain.py

• Education typed AG-UI stream: PASS
• Education memory round-trip: PASS
• Coop-finance typed AG-UI stream: PASS
• Coop-finance memory round-trip: PASS
• Swap parity: PASS
• Transition metrics: PASS
• Pytest eval subprocess: PASS
• PROGRAM EXIT GATE: PASS

Exit-Gate Checklist

• Education and coop-finance run through the same engine.
• Streaming surface exercised for both domains.
• Memory write-back demonstrated for both domains.
• Cross-session working-memory persistence demonstrated.
• run_swap_parity summary printed.
• Transition-metrics report printed.
• Eval subprocess uses a bounded timeout.
• Full non-manual test suite passes.
• primer-eval passes 7/7.
• All three demos pass.
• Production handoff documentation added.

Notes

This PR is primarily an assembly and handoff change. It reuses the existing orchestration, memory, domain-pack, parity, and evaluation machinery rather than introducing a separate demo-specific engine path.

The dual-domain demo exits with status 0 only when every required program-exit leg passes.

[AQUINTERO446]

Review — dual-domain exit demo + production handoff

Thorough review done in an isolated worktree (ruff 0.15.8 run, demo API surface traced against source). Code is functionally sound, but the PR fails ruff check . — a gate the handoff doc itself requires — so requesting changes for a one-command fix.

🔴 Critical — ruff check . fails (4 × I001)

Despite the chore: restore repo-wide ruff compliance commit, uv run ruff check . reports 4 unsorted import blocks (inline comments below). In each file the bare import capillary_actions_sdk was moved down into the first-party group, while the from capillary_actions_sdk.… lines stayed in the third-party group; ruff wants the bare import at the top of the third-party group. docs/proposal/handoff.md lists uv run ruff check . in the Program Exit Checklist, so the PR contradicts its own gate.

Fix: uv run ruff check --fix . (auto-fixable) — this also removes the entire import-churn diff in those 4 otherwise-untouched files. ruff format --check passes.

🟡 Warnings

• demos/demo_dual_domain.py uses from demo_education import run_memory_roundtrip — a sibling-module import that only resolves because the script's own dir is on sys.path[0]. Works via the documented uv run python demos/demo_dual_domain.py, but breaks under python -m demos.demo_dual_domain.

🟢 Suggestions

• demos/demo_education.py writeback content changed from {"courses": ["demo_course"]} → {} (inline note). Verified benign — an empty dict still creates a surviving entry, so the roundtrip pass/fail is unaffected — but the demo now round-trips an empty payload, which is less illustrative. Confirm intentional.

✅ Verified sound

• New demo API surface all resolves: find_eval_case("coop-finance") → build_finance_eval_case(); run_engagement_streaming(skill_name, subject_id, thread_id, input_data) signature matches; EngagementEvalCase.input_data exists; run_eval_suite/format_report present.
• run_memory_roundtrip refactor is clean and ruff-clean; test-file changes are formatting/quote-normalization only (no logic change).

Verdict: FAIL on the ruff gate — but it's a one-command fix. Run ruff check --fix, force-push, and this is a PASS.

[AQUINTERO446]

🔴 ruff check (I001): the bare import capillary_actions_sdk belongs at the top of the third-party group, above from capillary_actions_sdk.…, not here in the first-party block. ruff check --fix corrects it.

[AQUINTERO446]

🔴 ruff check I001 fails here — same misordered import capillary_actions_sdk. Run ruff check --fix.

[AQUINTERO446]

🔴 ruff check I001 fails here — same misordered import capillary_actions_sdk. Run ruff check --fix.

[AQUINTERO446]

🔴 ruff check I001 fails here — same misordered import capillary_actions_sdk. Run ruff check --fix.

[AQUINTERO446]

🟢 Writeback content is now {} (was {"courses": ["demo_course"]}). Verified benign — an empty dict still creates a surviving entry so the roundtrip still passes — but the demo now round-trips an empty payload, which is less illustrative of real content persistence. Intentional?

[ctrl-is]

I reran the Ruff gate directly on the current PR branch:

uv run ruff check --fix .
uv run ruff format --check .
uv run ruff check .

The results were:

All checks passed!
89 files already formatted
All checks passed!

ruff check --fix . did not produce any changes on my branch, so there was nothing additional to commit or push. The branch is currently Ruff-clean locally.

I also previously ran the full program-exit validation on this branch, with the full test suite, eval suite, primer-eval, and all three demos passing.