feat: v0.4.1 — meta-progression nudges (coverage hook + intake suggestion)

[broomva]

Summary

Closes the meta-progression gap from v0.4.0. v0.2.0 wired per-prompt routing; v0.4.0 shipped observability; v0.4.1 wires the agent-facing nudges so the system progresses without requiring the user to remember to run `role-x suggest`.

Added

• `role-x coverage` — brief registry-health summary; silent when fire-rate ≥30% + sanitized capture on
• `scripts/role-x-coverage-hook.sh` — `SessionStart` hook wrapper with 24h cooldown
• In-prompt authoring nudge — when intake routes to `_meta` only AND prompt is domain-rich (≥8 words, ≥4 distinct meaningful tokens), append a one-line `role-x init ` suggestion to the intake context
• 8 new tests (30 → 38)
• SKILL.md "When to invoke" expanded with meta-progression discipline
• CHANGELOG v0.4.1

Two complementary nudges

Cadence	Mechanism	Trigger
Per-prompt	Intake context appendix	`_meta` only AND domain-rich prompt
Per-session (≤1/24h)	SessionStart hook → `coverage`	Fire-rate < 30% OR sanitized capture off

Both non-blocking, silent-when-healthy. Analogous to P8 skill-freshness — nudge but never gate.

Live verification

```bash
$ role-x coverage --since 7d
[role-x coverage] 43 events over 7d. Fire-rate: 12% (low).
Sanitized prompt capture is OFF — cluster discovery disabled. Enable: /Users/broomva/.config/broomva/role/config.json
Body: {"capture_sanitized_prompt": true, "sanitization_strategy": "keywords"}
Author next: `role-x init ` (status: candidate, promote on rule-of-three).

$ role-x intake --prompt "draft a thorough strategic brief about quarterly rollout plans for partner onboarding initiatives" --workspace ~/broomva
[role-x intake — P17 reflex applied]
Lens(es): _meta only (no domain lens scored ≥2)
Mode: augment
…
Note: no domain lens scored ≥2 for this prompt. If this kind of work recurs,
consider expanding the registry: `role-x init draft-thorough` (status: candidate).
```

Test plan

• 38/38 pytest pass (Python 3.11 + 3.12)
• Backward compat: 30 prior tests unchanged
• Live smoke against your actual events.jsonl
• Privacy invariant preserved: no new captured fields; nudge computed at runtime

Workspace wiring follow-up

The SessionStart hook is installed by `npx skills update -g role-x` but inert until `.claude/settings.json` registers it. Separate PR on broomva/workspace adds:

```json
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "$HOME/.agents/skills/role-x/scripts/role-x-coverage-hook.sh",
"timeout": 5
}
]
}
]
```

🤖 Generated with Claude Code

Summary by CodeRabbit

v0.4.1 Release Notes

• New Features

  • Added role-x coverage subcommand for session-start health monitoring, with silent operation when healthy and reporting when issues are detected
  • Introduced authoring nudges directing users to initialize domains when prompts route only to metadata level

• Documentation

  • Updated CHANGELOG, README, and skill documentation with v0.4.1 features, new subcommands, and meta-progression workflow guidance

• Tests

  • Added eight new tests validating coverage monitoring and authoring nudge behavior across various scenarios

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 10361f3a-b259-458e-b42a-366b4be8f535

📥 Commits

Reviewing files that changed from the base of the PR and between 22c7f53 and 24cac91.

📒 Files selected for processing (6)

• CHANGELOG.md
• README.md
• SKILL.md
• scripts/role-x-coverage-hook.sh
• scripts/role-x.py
• tests/test_role_x.py

---

📝 Walkthrough

Walkthrough

This PR releases v0.4.1 of role-x, adding intake-level authoring nudges for substantive _meta-only prompts and a new health-reporting coverage subcommand with SessionStart hook integration to address meta-progression gaps.

Changes

v0.4.1 Release: Intake Nudge and Coverage Reporting

Layer / File(s)	Summary
v0.4.1 Release Documentation CHANGELOG.md, README.md, SKILL.md	Release notes document the intake nudge, coverage subcommand, hook script integration, and meta-progression discipline strategy with thresholds and scenarios to avoid meta-actions.
v0.4.1 Constants: Domain-Rich Heuristics and Coverage Thresholds scripts/role-x.py (266–277)	Constants define domain-rich prompt detection (word/token minimums) and coverage fire-rate health baseline used by intake and coverage features.
Intake Authoring Nudge Feature scripts/role-x.py (666–715, 750–751), tests/test_role_x.py (686–736)	Intake detects substantive _meta-only prompts and generates "role-x init" suggestions; helper functions identify domain-rich content and build candidate lens slugs; cmd_intake integrates nudge into selection output. Three tests verify nudge appears for rich meta-only prompts and is suppressed when lens fires or prompt is short.
Coverage Subcommand: Fire-Rate Health Reporting scripts/role-x.py (943–995, 1171–1189), tests/test_role_x.py (738–822)	Coverage subcommand reads events.jsonl, computes lens fire-rate over a window, and stays silent when healthy or prints health hints when fire-rate is low or sanitization is disabled. CLI parser wires --since, --events-path, --min-events, and --force. Five tests cover healthy/low fire-rate conditions, sanitization presence/absence, and --force override behavior.
Coverage Hook Script with Cooldown scripts/role-x-coverage-hook.sh (1–54)	Bash hook enforces strict mode, discovers Python, applies 24-hour cooldown via stamp file, executes coverage --since 7d with error suppression, and guarantees exit 0 for non-blocking SessionStart integration.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• broomva/role-x#1: Extends the existing cmd_intake and intake event pipeline from PR #1 by adding _meta-only "role-x init" authoring nudges to intake output, using the same events.jsonl infrastructure introduced in the earlier UserPromptSubmit integration.

Poem

🐰 A nudge for the meta, a coverage report,
Health checks at the start of each coding cohort,
When lenses run dry and the prompts stand tall,
Suggestion for new ones—progress through it all! 🌱

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/v0.4.1-coverage-hook

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}