Add wellness/mental_coach skill resolving #148

[mrmasa88]

Summary

Adds a new universal wellness/mental_coach skill that resolves #148.

It is a deterministic compliance + coaching firewall a parent agent calls before
generating wellness replies: it triages crisis signals first, enforces non-clinical
scope limits, retrieves grounded KB chunks with citations, optionally runs a scope
evaluator, and returns structured JSON (policy_status, citations,
disclaimers_required, final_context_for_agent, ...).

This is the generic, PyPI-shippable base skill — generic enough for any operator,
with no org-specific overlay mixed in.

Fixes #148

Type of change

• New skill

What's included

• skills/wellness/mental_coach/ full bundle: manifest.yaml, skill.py,
  instructions.md, card.json, test_skill.py, __init__.py
• Modular logic: crisis_gate.py, constraints.py, kb_provider.py, resources.py
• Embedded KB under kb/: corpus.json, hard_constraints.yaml, crisis_resources.json
• Catalog page docs/skills/mental_coach.md + new Wellness row in docs/skills/README.md
• examples/mental_coach_demo.py + examples/README.md row
• CHANGELOG.md [Unreleased] entry
• New category wellness/ (proposed in [New Skill]: wellness/mental_coach, grounded wellness coaching with crisis triage and regulatory guardrails #148; flagging for maintainer confirmation)

Safety design

• Deterministic crisis gate runs FIRST, before retrieval, with no LLM dependency.
• Biased to over-escalation: on a crisis signal, policy_status = ESCALATE, coaching
  is suppressed (no retrieval), and jurisdiction-appropriate crisis resources are returned.
• Hard constraints block diagnosis / medication / clinical interpretation, and resist
  prompt-injection attempts.
• Negation handling routes ambiguous phrasing to CAUTION rather than OK.
• EN-first v0.1: non-English input is routed to CAUTION + resources rather than passed silently.
• Crisis resources are real, source-verified public-safety data (US/UK/FR/DE/ES/IT/EU/GLOBAL)
  with 24/7 flags.

Skill checklist

• skills/wellness/mental_coach/ exists with full bundle
• manifest.yaml: name, version, description, parameters, constitution, real issuer
• skill.py: deterministic, JSON-serializable returns, safe error handling
• instructions.md: when to use, how to interpret output, limitations
• card.json issuer matches manifest
• test_skill.py passes (crisis ESCALATE, blocked diagnosis, injection, coaching retrieval, non-EN CAUTION)
• docs/skills/mental_coach.md + catalog row in docs/skills/README.md
• Usage Examples (Gemini, Claude, OpenAI, DeepSeek, Ollama) on the catalog page
• pytest tests/test_skill_issuer.py passes
• SkillLoader.load_skill("wellness/mental_coach") works
• examples/README.md updated
• No placeholders under skills/
• CHANGELOG.md updated under [Unreleased]

Tests

• black . clean, flake8 . clean
• pytest skills/ — 85 passed
• pytest tests/ — 76 passed
• pytest skills/wellness/mental_coach/test_skill.py + tests/test_skill_issuer.py — 12 passed
• Local demo: coaching OK, crisis ESCALATE (988 surfaced), clinical request BLOCKED

Note for maintainer (issuer)

For v0.1 the issuer is set to me (mrmasa88, AO) so the required issuer fields validate.
Ross Peili is intended as the primary issuer — I'll confirm his contact and update the
issuer before merge. Happy to align on author/issuer attribution however you prefer.

[rosspeili]

Thanks for this @mrmasa88, exceptional work on 148.

Before merge, please:

1. Issuer, [New Skill]: wellness/mental_coach, grounded wellness coaching with crisis triage and regulatory guardrails #148 calls for Ross Peili & Mr. Masa (AO Protocol) with both real contact emails in manifest.yaml. Right now only your noreply GitHub email is set. Please align issuer in manifest.yaml, card.json, docs/skills/mental_coach.md, and docs/skills/README.md (happy to pair on exact wording). You don't need to add me, as I offered the scafold so you could work on it, add just your name / gh username and real email, not github no reply, as it will fail CI tests and be rejected.

Optional but appreciated in the same push:

2. Load full manifest.yaml in skill.manifest (same pattern as pdf_form_filler / recent wallet_screening fix).
3. Add wellness to the skill categories table in CONTRIBUTING.md.

Once the issuer most importantly is sorted, we should be good to merge, but you can include the housekeeping tweaks above too in the same pr. Nice and careful skill for a sensitive domain overall. Well done <3

[mrmasa88]

Hi @rosspeili . Thanks for your review and feedback.

Updated PR #174 with both of your points:

1. Issuer/contact is now my real email (masa88keith@gmail.com) across the manifest, card, and docs — no more github no-reply.
2. Added a health/mental-health disclaimer on the catalog page, using hendobox / rizzoMartin as reference.

Git author stays clean (just me, no AI co-authors). Whenever you have a moment to re-review, much appreciated.

[rosspeili]

Thanks again @mrmasa88, the follow-up commit addresses the issuer blocker cleanly.

Yet, before we merge, please:

1. Sync with current main and resolve the CHANGELOG.md conflict

Your branch is behind upstream (main now includes #180 / #86 test layout and #173 wallet_screening fixes). Recommended path:

git fetch https://github.com/ARPAHLS/skillware.git main
git checkout feat/issue-148-wellness-mental-coach
git rebase FETCH_HEAD
# or: git merge FETCH_HEAD

When CHANGELOG.md conflicts under [Unreleased], keep all sections, do not drop upstream entries. Target shape:

## [Unreleased]

### Added
- **`wellness/mental_coach`**: … (#148).

### Changed
- **Tests**: Moved `tests/test_mica_module.py` to `tests/skills/compliance/…` (#86).
- **`wellness/mental_coach`**: Set real issuer contact email and add health disclaimer… (your follow-up).

### Fixed
- **`finance/wallet_screening`**: … (#173).

Then push:

git push --force-with-lease

(Use a normal git push instead if you merged rather than rebased.)

2. Housekeeping (same push if you can)

• Load full manifest.yaml in MentalCoachSkill.manifest (same pattern as wallet_screening / pdf_form_filler).
• Add wellness to the skill categories table in CONTRIBUTING.md.
• Add a wellness/mental_coach row to docs/usage/agent_loops.md (mental_coach_demo.py as local execute; provider columns → catalog page).
• Update the PR description, remove the stale “Ross Peili as primary issuer” note, as issuer is settled with your real mail.

3. Re-verify after rebase if want

python -m flake8 .
pytest skills/wellness/mental_coach/test_skill.py
pytest tests/test_skill_issuer.py
pytest skills/ tests/

Once that’s in, we should be good to merge. Optional later: a short Testing block on docs/skills/mental_coach.md, not blocking for this initial pr.

Again, super clean work on a sensitive domain like mental health, appreciate the careful crisis-first design. <3 Let me know if you need help or direction.