codymaster 4.6.0 → 5.2.0

package/skills/cm-continuity/SKILL.md

@@ -52,21 +52,9 @@ cm continuity migrate
 # Export SQLite back to JSON (backup)
 cm continuity export
 
-# ── OpenViking backend (optional) ────────────────────────
-# 1. Install OpenViking server (Python 3.10+)
-pip install openviking --upgrade
-
-# 2. Configure ~/.openviking/ov.conf with embedding provider, then start:
-openviking start          # Runs on localhost:1933 by default
-
-# 3. Switch CodyMaster to use OpenViking in .cm/config.yaml:
-#    storage:
-#      backend: viking
-#      viking:
-#        host: localhost
-#        port: 1933
-#        workspace: codymaster
-#        timeout: 60000
+# ── Legacy config note ────────────────────────────────────
+# CodyMaster's supported default path is SQLite + FTS5.
+# Older configs may still say `storage.backend: viking`; CodyMaster now warns and falls back to SQLite.
 ```
 
 ## The Protocol
@@ -187,12 +175,12 @@ Tier 3: LONG-TERM MEMORY (30+ days, only if reinforced)
       · decisions table + decisions_fts
       · skill_outputs per session/chain
       · indexes table (cached L0/L1 content + staleness hash)
-  → Optional: OpenViking backend (storage.backend: viking in .cm/config.yaml)
+  → Legacy config note: `storage.backend: viking` now falls back to SQLite
       · True vector semantic search — finds "async timeout" even when you query "network delay"
       · L0/L1/L2 auto-generated by engine — no manual cm continuity index needed
       · Session compression + long-term memory extraction built-in
       · Graph relations between memories (link/unlink)
-      · Setup: pip install openviking && openviking start
+      · No separate OpenViking setup remains in the supported runtime
   → Fallback: .cm/memory/learnings.json + decisions.json (kept for compat)
   → L0 indexes: .cm/learnings-index.md (~100 tok), .cm/skeleton-index.md (~500 tok)
       · Auto-regenerated on addLearning() + on demand via cm continuity index
@@ -215,27 +203,38 @@ Tier 5: STRUCTURAL CODE MEMORY (optional — code-heavy projects)
 **context bus        = "what did upstream skills produce in this chain?"**
 **L0 indexes         = "cheapest possible memory load (~600 tokens)"**
 **context.db         = "keyword search across all learnings + decisions"**
-**OpenViking (opt.)  = "semantic vector search + auto L0/L1 + session compression"**
+**Legacy `viking` config = "compatibility fallback to SQLite, not a separate backend"**
 **qmd (optional)     = "find what was written across hundreds of docs"**
 
-### MCP Context Server (Claude Desktop integration)
-
-Seven tools exposed over stdio to Claude Desktop and MCP-compatible clients:
+### MCP Context Server (Claude Desktop, Goose, and any MCP client)
 
-| Tool | Purpose |
-|---|---|
-| `cm_query` | FTS5 keyword search — learnings, decisions, or both |
-| `cm_resolve` | Load any `cm://` URI at L0/L1/L2 depth |
-| `cm_bus_read` | Read live context bus state |
-| `cm_bus_write` | Publish skill output to the bus |
-| `cm_budget_check` | Pre-flight token check by category |
-| `cm_memory_decay` | Archive expired learnings (supports dry_run) |
-| `cm_index_refresh` | Regenerate L0 indexes on demand |
+Fifteen tools exposed over stdio — start with `cm mcp-serve`:
 
 ```bash
-# Get install snippet for Claude Desktop config
-cm continuity mcp
-```
+# Start MCP server (stdio)
+cm mcp-serve --project /path/to/project
+
+# Print config snippet for Claude Desktop or Goose
+cm mcp-serve --print-config
+```
+
+| Tool | Purpose | Since |
+|---|---|---|
+| `cm_query` | FTS5 keyword search — learnings, decisions, or both | v4.5 |
+| `cm_resolve` | Load any `cm://` URI at L0/L1/L2 depth | v4.5 |
+| `cm_bus_read` | Read live context bus state | v4.5 |
+| `cm_bus_write` | Publish skill output to the bus | v4.5 |
+| `cm_budget_check` | Pre-flight token check by category | v4.5 |
+| `cm_memory_decay` | Archive expired learnings (supports dry_run) | v4.5 |
+| `cm_index_refresh` | Regenerate L0 indexes on demand | v4.5 |
+| `cm_plan` | Sprint + pipeline snapshot bridge | v4.8 |
+| `cm_review` | Review artifact hints | v4.8 |
+| `cm_qa` | QA workflow hints | v4.8 |
+| `cm_deploy` | Deploy workflow hints | v4.8 |
+| `cm_search` | Search learnings/decisions (alias) | v4.8 |
+| `cm_memory_query` | Memory search (alias) | v4.8 |
+| `cm_memory_write` | Persist a learning with auto-detected category, scope, TTL | v5.1 |
+| `cm_natural` | NLI router: "remember that…" / "forget…" / "what did we learn…" | v5.1 |
 
 ### cm:// URI Scheme
 

package/skills/cm-design-studio/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: cm-design-studio
+description: "Use when you need to create 2-3 UI/UX design variants and document a repeatable handoff before coding."
+---
+# cm-design-studio
+
+> Local design-variant workspace: checklist, named variants, and a handoff stub—no external MCP required.
+
+## When to use
+
+- You want **2–3 UI/UX variants** documented before coding.
+- You need a **repeatable handoff** from design choice to implementation agents.
+- You prefer **files under `.cm/`** over ad-hoc chat-only decisions.
+
+## Steps
+
+1. From the repo root: `cm design-studio init`
+2. Edit `.cm/design-studio/CHECKLIST.md` and `VARIANTS.md` (name options A/B/C).
+3. Pick a variant; complete `.cm/design-studio/HANDOFF.md` (screens, tokens, prompt stub).
+4. Run implementation skills (e.g. `cm-execution`, `cm-tdd`) **using the HANDOFF prompt stub** as the single source of truth.
+
+Optional: `cm design-studio status` — list artifact files.
+
+## Output
+
+- `.cm/design-studio/README.md` — happy path
+- `.cm/design-studio/CHECKLIST.md`
+- `.cm/design-studio/VARIANTS.md`
+- `.cm/design-studio/HANDOFF.md`
+
+## Related
+
+- ADR 003 (`docs/adr/003-skill-distro-and-meta.md`) for pack layout when publishing skills.
+- `cm suggest` may recommend other skills based on git + sprint state.

package/skills/cm-ecosystem-roadmap/SKILL.md

@@ -0,0 +1,15 @@
+---
+name: cm-ecosystem-roadmap
+description: "Use when exploring the CodyMaster skill ecosystem roadmap, marketplace, or distro validation."
+---
+# cm-ecosystem-roadmap — marketplace & distros
+
+**In CLI today:** `cm distro validate <dir>` checks skill folder layout; see **ADR 003** (`docs/adr/003-skill-distro-and-meta.md`) for `meta.json` + tmpl rules.
+
+**Backlog** (community scale-out):
+
+- **`cm marketplace`** — starred skills, semver, dependency graph.
+- **`cm install`** / **`cm distro create`** — preset skill packs + branding (SaaS, e-commerce, mobile, agency).
+- **Publish** — npm and/or git tags as distribution channels.
+
+Reuse **meta.json** + `SKILL.md.tmpl` from `scripts/build-skills.mjs` for reproducible skill packages.

package/skills/cm-engineering-meta/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: cm-engineering-meta
+description: "Use when looking up quick wins, access patterns, or voice map for the engineering meta layer."
+---
+# cm-engineering-meta — quick wins + access + voice map
+
+## Search before building
+
+Before adding infrastructure, search in three layers:
+
+1. **Tried-and-true** — patterns already in this repo / sibling services.
+2. **New-and-popular** — current docs for your stack version.
+3. **First-principles** — only when 1–2 don’t apply.
+
+## AskUserQuestion format
+
+When asking the human to choose:
+
+- Short **context** (what you already know).
+- Clear **question**.
+- **RECOMMENDATION** (one option you’d pick and why).
+- Lettered options **A / B / C** (not vague yes/no).
+
+## Review readiness dashboard (ASCII)
+
+Before ship, print a table:
+
+```
+| Gate        | Status | Notes |
+|-------------|--------|-------|
+| Tests       | ?      |       |
+| Lint/Type   | ?      |       |
+| Secrets     | ?      |       |
+| Manual QA   | ?      |       |
+```
+
+## Completeness gap (code review)
+
+Flag when an **80% solution** is chosen but the **100%** path costs **< 30 minutes** (tests, edge case, docs).
+
+## Investigate Iron Law
+
+- Do **not** patch without a **root cause** hypothesis.
+- After **three** failed fix attempts, stop and question architecture or gather more data.
+
+## Access controls (Goose-style)
+
+- Maintain lists: **autonomous_ok** vs **confirm_required** skill groups (see `.cm/config.example.yaml`).
+- Respect “stop suggesting skill X” in session notes.
+
+## Provider abstraction
+
+Prefer interfaces for LLM calls so **cm-second-opinion** can swap `OPENAI_API_KEY` / future providers without rewriting skills.
+
+## Proactive skill suggestion
+
+Infer stage from files touched and git state:
+
+- Many `test/` edits → suggest **cm-test-gate**.
+- `Dockerfile` / deploy scripts → **cm-safe-deploy** + **cm canary**.
+- `rm` / migration scripts → **cm-guardian** + **cm-secret-shield**.
+
+## Voice-friendly triggers (examples)
+
+| Phrase (approx.) | Skill / command |
+|------------------|-----------------|
+| “Run a security check” | cm-secret-shield / cm-security-gate |
+| “Test the website” | cm browse + cm qa-visual |
+| “Code review this” | cm-code-review |
+| “Deploy safely” | cm-safe-deploy |
+| “Log what went wrong” | `cm retro --note "…"` |
+
+Use Whisper / AquaVoice → paste transcript; map keywords to the table above.

package/skills/cm-growth-hacking/SKILL.md

@@ -1,17 +1,6 @@
 ---
 name: cm-growth-hacking
-description: |
-  Growth Hacking Engine — Bottom Sheet + Calendar + Trigger + CRO Tracking.
-  Modular system for booking popups, lead capture, flash sales, surveys, re-engagement.
-  Auto-detect industry → select pattern → generate bottom sheet + calendar CTA + tracking.
-  Zero dependencies, works on any static or dynamic site.
-  
-  Kế thừa và liên kết với: cm-booking-calendar, cm-ads-tracker, cm-google-form, cm-readit, cm-ux-master.
-  
-  ALWAYS trigger for: bottom sheet, popup, đặt lịch, booking popup, lead capture, exit intent,
-  engagement, "tạo popup", "thêm bottom sheet", "popup đặt lịch", "nhắc lịch hẹn",
-  "add to calendar", "google calendar", "apple calendar", flash sale popup, survey popup,
-  "tăng conversion", "giảm bounce", re-engagement, "popup CTA"
+description: "Bottom-sheet and popup growth system: booking CTAs, calendars, lead capture, surveys, re-engagement, with CRO tracking hooks. Zero-deps; works static or dynamic sites. Works with cm-booking-calendar, cm-ads-tracker, cm-google-form, cm-readit, cm-ux-master."
 allowed-tools: Read, Write, Edit, Glob, Grep, Browser
 version: 1.0
 priority: HIGH

package/skills/cm-guardian-runtime/SKILL.md

@@ -0,0 +1,26 @@
+---
+name: cm-guardian-runtime
+description: "Use when you need to check if a destructive command is blocked or run guardian freeze checks."
+---
+# cm-guardian-runtime — destructive command & freeze checks
+
+## Commands
+
+```bash
+cm guardian check -- git push --force origin main    # exits 1 if blocked
+cm guardian path-check --file ./src/app.ts --roots src,lib
+```
+
+## Behaviour
+
+- Regex set for `rm -rf`, `DROP TABLE`, `git push --force`, `git reset --hard`, pipes to shell, etc.
+- Prefix whitelist includes `npm run build`, `npm test`, `npx vitest`.
+- Violations append to `.cm/guardian.log`.
+
+## Investigate / debug mode
+
+When using **cm-debugging** or root-cause work, treat **freeze roots** as mandatory: only edit inside allowed directories until the hypothesis is proven.
+
+## Config
+
+See `.cm/config.example.yaml` → `guardian:`. Hook patterns (Cursor / Codex): [docs/workflows/guardian-hooks.md](../../docs/workflows/guardian-hooks.md) (repo root).

package/skills/cm-mcp-engineering/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: cm-mcp-engineering
+description: "Use when you need to interact with the MCP engineering bridge tools (cm_plan, cm_review, cm_qa, cm_deploy, cm_search)."
+---
+# cm-mcp-engineering — MCP tools on context server
+
+The same binary as memory MCP (`dist/mcp-context-server.js`) now exposes **engineering bridge** tools:
+
+| Tool | Purpose |
+|------|---------|
+| `cm_plan` | Sprint state + artifact paths + next skill hint |
+| `cm_review` | Preview `.cm/sprint/artifacts/review.md` |
+| `cm_qa` | Pointers to browse daemon + `cm qa-visual` |
+| `cm_deploy` | Hints for safe deploy + canary |
+| `cm_search` | Learnings + decisions search |
+| `cm_memory_query` | Same backing store, alias-style |
+
+Existing tools unchanged: `cm_query`, `cm_resolve`, `cm_bus_read`, `cm_bus_write`, `cm_budget_check`, `cm_memory_decay`, `cm_index_refresh`.
+
+## Config
+
+Point `--project` at the repo root (or `CM_PROJECT_PATH`).

package/skills/cm-notebooklm/SKILL.md

@@ -1,22 +1,6 @@
 ---
 name: cm-notebooklm
-description: |
-  CodyMaster NotebookLM — Cloud-based AI brain/soul engine. Stores the most
-  valuable knowledge (skills, lessons learned, coding experiences, key decisions)
-  into Google NotebookLM for cross-machine sync and AI-powered recall.
-  Combines cm-dockit (codebase → docs) + cm-deep-search (local BM25) +
-  NotebookLM (cloud AI memory + podcast + flashcards).
-
-  Offers LOCAL vs CLOUD choice for large codebases. Auto-sync mechanism.
-  Selective indexing — only high-value content, not everything.
-
-  Use when user says: "notebooklm", "notebook lm", "nlm", "nạp kiến thức",
-  "knowledge base", "create notebook", "sync skills to notebook", "tạo notebook",
-  "knowledge memory", "podcast từ skills", "flashcards từ docs",
-  "add to notebooklm", "query notebooklm", "hỏi notebooklm",
-  "lưu kinh nghiệm", "bộ nhớ AI", "AI memory", "tạo podcast",
-  "codymaster notebook", "skill notebook", "sync knowledge",
-  "cloud brain", "soul sync", "cross-machine sync".
+description: "Sync high-value dev knowledge (skills, decisions, lessons) into Google NotebookLM for cloud recall, podcasts, and flashcards. Pairs with Dockit/deep-search. Use for NotebookLM, nlm, knowledge base, skill sync, or cross-machine AI memory."
 ---
 
 # Goal

package/skills/cm-post-deploy-canary/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: cm-post-deploy-canary
+description: "Use after deployment to run smoke tests and post-deploy canary checks via the browse daemon."
+---
+# cm-post-deploy-canary — smoke + browse tail
+
+## CLI
+
+```bash
+cm canary --url https://app.example.com
+cm canary --url https://app.example.com --browse-port 17395 --token "$CM_BROWSE_TOKEN"
+```
+
+## Flow
+
+1. **HTTP GET** the URL (status < 400).
+2. Optionally pull **browse daemon** `/console` for recent browser errors after deploy.
+
+## Next
+
+- Wire into **cm-safe-deploy** as a final step.
+- Add programmatic CWV (Lighthouse) when you need baselines per PR.

package/skills/cm-project-bootstrap/SKILL.md

@@ -1318,6 +1318,16 @@ Add this line to the AGENTS.md "Important Rules" section:
 
 ```markdown
 - Read `.cm/CONTINUITY.md` at the start of every session for context
+- Rely on `.cm/project-skills.md` for skill discovery rather than external indexes
+```
+
+### Step 5: Build Local Project Skills Index
+
+Run the CodyMaster CLI indexer to detect the tech stack deterministically and pre-compile the needed community skills without wasting LLM tokens.
+
+```bash
+# This scans package.json/go.mod/etc and outputs to .cm/project-skills.md
+npx cm index skills
 ```
 
 ### Why This Saves Tokens
@@ -1373,4 +1383,5 @@ After bootstrap, the project MUST have:
 ✅ production branch          — Production deploys
 ✅ First commit               — "chore: bootstrap with cm-project-bootstrap v2.0"
 ✅ .cm/CONTINUITY.md           — Working memory for AI context persistence
+✅ .cm/project-skills.md       — Localized token-efficient skill discovery index
 ```

package/skills/cm-qa-visual-cli/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: cm-qa-visual-cli
+description: "Use when you need to take screenshots or run visual QA via the browse daemon CLI."
+---
+# cm-qa-visual-cli — screenshot via browse daemon
+
+## Prerequisites
+
+`cm browse start` running with the same `CM_BROWSE_TOKEN`.
+
+## CLI
+
+```bash
+cm qa-visual --url http://localhost:5173 --port 17395
+```
+
+Writes `cm-qa-visual.png` in the current working directory.
+
+## Next
+
+- Diff against golden images for visual regression.
+- Map `git diff` → affected routes (project-specific heuristics).

package/skills/cm-retro-cli/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: cm-retro-cli
+description: "Use at end of sprint to append operational learnings as structured JSONL to the project retro log."
+---
+# cm-retro-cli — operational learnings JSONL
+
+## Append
+
+```bash
+cm retro --project . --tool claude --note "Forgot to run gate before push; CI failed on lint."
+```
+
+Stored in `.cm/operational-learnings.jsonl`.
+
+## Summary
+
+```bash
+cm retro --project . --summary
+```
+
+## Use with skill evolution
+
+Feed highlights into **cm-skill-evolution** / project learnings DB so future sessions avoid repeating mistakes.

package/skills/cm-second-opinion-cli/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: cm-second-opinion-cli
+description: "Use when you need a cross-model review or second opinion on a diff or code change."
+---
+# cm-second-opinion-cli — cross-model review stub
+
+## CLI
+
+```bash
+cm second-opinion --file /tmp/my.diff
+```
+
+- With `OPENAI_API_KEY`, calls **OpenAI chat completions** (`CM_SECOND_OPINION_MODEL` optional, default `gpt-4o-mini`).
+- Without key, prints a **stub** reminder (no network).
+
+## Safety
+
+- **Never** paste secrets or production credentials into the diff file.
+- Prefer unified diffs of **application code** only.
+
+## Roadmap
+
+Add Anthropic / Google / Ollama providers via shared provider interface (see **cm-engineering-meta**).

package/skills/cm-secret-shield/SKILL.md

@@ -79,8 +79,8 @@ ROTATION is not optional after a leak.
 // ❌ NEVER write code like this:
 const API_KEY = "sk-proj-abc123def456ghi789";
 const SUPABASE_KEY = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";
-const DB_PASSWORD = "MyP@ssw0rd123!";
-fetch('https://api.example.com', { headers: { Authorization: 'Bearer sk-...' } });
+const DB_PASSWORD = "<YOUR_SECURE_PASSWORD>";
+fetch('https://api.example.com', { headers: { Authorization: 'Bearer <YOUR_TOKEN>' } });
 
 // ✅ ALWAYS write code like this:
 const API_KEY = process.env.API_KEY;

package/skills/cm-security-gate/SKILL.md

@@ -1,4 +1,5 @@
 ---
+name: cm-security-gate
 description: Pre-production security audit and vulnerability scanning. Run Snyk + Aikido dependency scans, OWASP analysis, and set up automated GitHub security checks with Jules. Use when asked to 'run security check', 'security audit', 'kiểm tra bảo mật', 'vulnerability scan', 'Snyk', 'OWASP', or before open-sourcing / commercializing a project.
 ---
 # cm-security-gate — Mandatory Security Audit & Vulnerability Gate

package/skills/cm-skill-chain/SKILL.md

@@ -37,8 +37,9 @@ Full skill names: `cm-brainstorm-idea`, `cm-planning`, `cm-tdd`, `cm-execution`,
 
 ## Built-in Chains
 
-### 🚀 feature-development (6 steps)
-`brainstorm-idea → planning → tdd → execution → quality-gate → safe-deploy`
+### 🚀 feature-development (up to 3 active steps)
+`brainstorm-idea* → planning → tdd → execution → quality-gate → safe-deploy*`
+*optional steps — only activated when task context scores them relevant
 
 ### 🐛 bug-fix (3 steps)
 `debugging → tdd → quality-gate`
@@ -46,12 +47,32 @@ Full skill names: `cm-brainstorm-idea`, `cm-planning`, `cm-tdd`, `cm-execution`,
 ### 📝 content-launch (3 steps)
 `content-factory → ads-tracker → cm-cro-methodology`
 
-### 🏗️ new-project (6 steps)
-`project-bootstrap → planning → tdd → execution → quality-gate → safe-deploy`
+### 🏗️ new-project (up to 3 active steps)
+`project-bootstrap → planning → tdd → execution → quality-gate → safe-deploy*`
+*optional steps selected by task relevance
 
 ### 🔍 cm-code-review (3 steps)
 `cm-code-review → quality-gate → safe-deploy`
 
+## Intelligent Skill Selection (v5.1)
+
+Chains no longer execute every step blindly. `selectTopSkills()` dynamically selects the **top 3 most relevant steps** for each task:
+
+```
+Task: "fix login timeout bug"
+  → Scores each step by keyword overlap with task description
+  → Mandatory steps (condition='always', optional=false) always included first
+  → Optional steps ranked by relevance score, capped at 3 total
+  → Result: debugging (score 105) → tdd (score 101) → quality-gate (score 100)
+```
+
+**Why it matters (SkillsBench research):**
+- 2-3 focused skills → **+18.6pp** task performance
+- 4+ skills → **+5.9pp**
+- Monolithic loading → **-2.9pp**
+
+If a chain has more than 3 mandatory steps, all mandatory steps run and a performance advisory is logged.
+
 ## Workflow
 
 1. **Start**: Use `chain auto` for auto-detection or `chain start` for specific chains

package/skills/cm-skill-evolution/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: cm-skill-evolution
+description: "Repair or extend CodyMaster skills with a three-mode loop: FIX, DERIVED, and CAPTURED, grounded in current repo tooling."
+---
+
+# cm-skill-evolution
+
+Use this skill after `cm-skill-health` identifies a degraded or broken skill, or when `cm advisory handoff --for cm-skill-evolution` produces a structured recovery note.
+
+## Modes
+
+### FIX
+Use when the skill should exist already but is inaccurate, broken, or partially missing.
+
+Checklist:
+- repair broken references
+- restore missing support files
+- align docs and profiles
+- re-run skill validation and test gate
+
+### DERIVED
+Use when the original promise was too ambitious, but the repo has enough primitives to ship a truthful MVP.
+
+Checklist:
+- keep the same user problem
+- reduce claims to what the code can support today
+- reuse existing repo building blocks instead of inventing a new subsystem
+
+### CAPTURED
+Use when the main value is operational learning rather than a new code path.
+
+Checklist:
+- append the lesson with `cm retro --project . --tool skill --note "..."`
+- record durable context in `.cm/CONTINUITY.md`
+- update the relevant skill so future sessions do not repeat the same failure
+
+## Evolution Loop
+
+1. Start from the health note.
+   - Preferred source: `cm advisory handoff --for cm-skill-evolution`
+2. Pick one mode only.
+3. Define the smallest truthful recovery.
+4. Patch the skill and its discovery surfaces.
+5. Verify:
+   - `npm run validate:skills`
+   - `npm run check:skills`
+   - repo test gate if code or docs wiring changed materially
+6. Capture the lesson in retro and continuity.
+
+## Decision guide
+
+- The feature existed and drifted: `FIX`
+- The changelog promised more than the repo ever shipped: `DERIVED`
+- The issue is mainly process and should inform future work: `CAPTURED`
+
+## Output
+
+```md
+## Skill Evolution
+- Skill: cm-...
+- Mode: FIX | DERIVED | CAPTURED
+- Change: ...
+- Verification: ...
+- Learning captured: yes | no
+```
+
+Preferred advisory input:
+
+```md
+## Advisory Handoff
+- Consumer: cm-skill-evolution
+- Skill: cm-...
+- Recovery path: FIX | DERIVED | CAPTURED | NONE
+- Confidence: 0.xx
+- Source analysis: EA-...
+- Task: ...
+- Status: completed | partial | failed
+- Evidence: ...
+- Selected skills: ...
+- Target skills: ...
+- Quality weight: 0.xx
+- Next step: ...
+```

package/skills/cm-skill-health/SKILL.md

@@ -0,0 +1,83 @@
+---
+name: cm-skill-health
+description: "Operational health review for CodyMaster skills using current repo signals: validate-skills, suggest, retro logs, memory, and test gates."
+---
+
+# cm-skill-health
+
+Use this skill when a CodyMaster skill feels stale, misleading, unreliable, or under-documented.
+
+## What it checks
+
+1. Discovery drift
+   - Is the skill present in `skills/`, docs indexes, profiles, and README surfaces?
+2. Invocation friction
+   - Does `cm suggest` point users to the skill when the task matches?
+3. Operational evidence
+   - Are there recurring failures or learnings in `.cm/operational-learnings.jsonl`?
+4. Contract health
+   - Does the skill reference commands, files, or paths that still exist?
+5. Release safety
+   - Does the repo still pass `npm run validate:skills`, `npm run check:skills`, and the test gate?
+
+## Workflow
+
+1. Confirm the symptom.
+   - Missing from docs
+   - Missing from profiles
+   - Broken references inside `SKILL.md`
+   - Repeated runtime pain in retro notes
+2. Compare the live skill against:
+   - `docs/skills/index.md`
+   - `skills/profiles/full.txt`
+   - `README.md`
+   - related changelog promises
+3. Scan evidence sources.
+   - `cm advisory handoff --for cm-skill-health`
+   - `cm suggest --project .`
+   - `cm retro summary --project .`
+   - `.cm/CONTINUITY.md`
+   - `rg` over `skills/`, `docs/`, and `src/`
+4. Score the issue.
+   - `healthy`: discoverable, accurate, references valid
+   - `degraded`: present but misleading or inconsistent
+   - `broken`: missing, invalid, or unusable
+5. Hand off to:
+   - `cm-skill-evolution` to repair or derive the next version
+
+## Output
+
+Produce a short health note:
+
+```md
+## Skill Health
+- Skill: cm-...
+- Status: healthy | degraded | broken
+- Symptoms: ...
+- Evidence: ...
+- Recovery path: FIX | DERIVED | CAPTURED
+```
+
+Preferred input contract:
+
+```md
+## Advisory Handoff
+- Consumer: cm-skill-health
+- Skill: cm-...
+- Recovery path: FIX | DERIVED | CAPTURED | NONE
+- Confidence: 0.xx
+- Source analysis: EA-...
+- Task: ...
+- Status: completed | partial | failed
+- Evidence: ...
+- Selected skills: ...
+- Target skills: ...
+- Quality weight: 0.xx
+- Next step: ...
+```
+
+## Red flags
+
+- Do not claim metric dashboards or automatic scoring unless the repo actually implements them.
+- Do not treat README marketing copy as proof that a skill exists.
+- Do not evolve the skill before identifying whether the problem is docs drift, packaging drift, or missing implementation.