feat: v0.2.0 — UserPromptSubmit hook integration (M2)

[broomva]

Summary

Ships v0.2.0 — the M2 milestone for role-x. Wires P17 intake into Claude Code's UserPromptSubmit event so lens selection fires automatically on every substantive prompt. Closes the reasoning-enforcement gap from v0.1.0.

What lands

• scripts/role-x-intake-hook.sh — graceful-fail shell wrapper (always exit 0; never blocks)
• scripts/role-x.py intake — new subcommand: signals → score → extends-chain → mode → event → context
• 7 new tests (13/13 total passing)
• CHANGELOG.md v0.2.0 entry
• README.md hook integration section

End-to-end verified

$ echo '{"prompt": "implement rust cargo tokio async runtime support",
         "session_id": "shell-hook-test"}' \
    | CLAUDE_PROJECT_DIR=$PWD ./scripts/role-x-intake-hook.sh

[role-x intake — P17 reflex applied]
Lens(es): rust-systems (signals: prompt_keywords=4); extension chain: rust-systems → _meta
Mode: augment
Quality bar (P14 dep-chain template):
  - P14 dep-chain trace produced …
  - P15 state snapshot surfaced …
  - …
  - MSRV declared in Cargo.toml is honored (workspace default: 1.85)
  - Edition 2024 idioms used (let-else, async traits where stable)
  - No `unwrap()` or `expect()` in non-test code unless explicitly documented
  - …
Context files to surface:
  - CLAUDE.md
  - AGENTS.md
  - core/life/CLAUDE.md
  - AGENTS.md#Conventions

Event persisted to ~/.config/broomva/role/events.jsonl:

{"ts":"2026-05-14T01:40:55.150348+00:00","event":"intake","session":"smoke-test","prompt_digest":"sha256:47b024614f0b…","prompt_word_count":12,"lenses_selected":["rust-systems"],"lenses_extended":["rust-systems","_meta"],"mode":"augment","mode_escalation_reason":null,"signals_matched":{"paths":0,"prompt_keywords":2,"branch_patterns":0,"linear_labels":0}}

Test plan

• python3 -m pytest tests/ -v → 13/13 pass
• Shell hook end-to-end with rust-keyword prompt → rust-systems lens selected, augment mode, full quality_bar output, event written
• Short prompt ("hi") → silent exit 0 (carve-out)
• Workspace without roles/ → silent exit 0
• Multi-domain prompt (rust + ts) → decompose mode
• Empty/non-matching prompt → _meta only, augment mode
• JSON stdin payload (Claude Code hook protocol) → parsed correctly
• CI matrix (Python 3.11 + 3.12) on push

Workspace wiring follow-up

Workspace .claude/settings.json registration of the new hook ships in a separate PR on broomva/workspace:

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

Carve-outs (silent exit 0)

• Prompts shorter than 3 words
• Workspace without a roles/ directory
• PyYAML not importable
• Python not found
• Any unexpected error in the wrapper (|| true)

These ensure the hook never breaks a user turn — bstack invariant for safety shields and reasoning-supplements.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added automatic intake hook integration that triggers on user prompts via Claude Code
  • New intake subcommand with lens selection, mode resolution, and structured event logging
  • Configured hook to gracefully handle missing dependencies without blocking user workflow

• Documentation

  • Updated README and CHANGELOG documenting v0.2.0 intake functionality
  • Added hook configuration snippets and testing examples

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 924cf545-b4d7-4547-ab77-1371e67ae600

📥 Commits

Reviewing files that changed from the base of the PR and between 0c6b524 and a4270f6.

📒 Files selected for processing (5)

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

---

📝 Walkthrough

Walkthrough

The PR implements v0.2.0's automatic intake hook: a Claude Code UserPromptSubmit integration that scores active lens roles against user prompts and git signals, emits events to events.jsonl, and renders contextual markdown output without blocking the user turn.

Changes

v0.2.0 Intake Hook Integration

Layer / File(s)	Summary
v0.2.0 Documentation and Feature Overview CHANGELOG.md, README.md	Updated release notes and roadmap document the intake subcommand, hook integration, event schema, and expanded test coverage (6→13 tests).
Hook Wrapper and CLI Entry Points scripts/role-x-intake-hook.sh, scripts/role-x.py (imports, parser)	New non-blocking Bash hook checks prerequisites and delegates to role-x intake subcommand. Python CLI wired with --prompt, --workspace, --session flags and stdin JSON fallback.
Workspace Discovery and Lens Data Loading scripts/role-x.py (helpers)	Added workspace root discovery via roles/ or .git, git signal collection (branch and touched files), lens frontmatter parsing, and prompt tokenization for scoring inputs.
Lens Scoring and Selection Algorithm scripts/role-x.py (helpers, algorithm)	Lens scoring computes matches across paths, prompt_keywords, and branch_patterns. Selection filters active lenses by threshold, resolves extends hierarchy, and decides augment vs decompose mode.
Event Emission and Context Rendering scripts/role-x.py (emission, rendering, cmd_intake)	Event emitter appends structured intake events to events.jsonl. Context renderer formats selected lenses and quality order into markdown blocks. cmd_intake orchestrates the full flow.
Test Infrastructure and Intake Test Coverage tests/test_role_x.py	Extended run_cli helper for stdin and environment overrides. New _seed_workspace builds minimal role-based workspaces. Comprehensive intake tests cover silent carve-outs, keyword selection, escalation, fallback, and hook stdin protocol.

🎯 3 (Moderate) | ⏱️ ~25 minutes

A rabbit hops through v0.2.0's design,
With hooks that score and lenses spin,
Events logged and modes decided fast,
All without a blocking task cast! 🐰✨

✨ 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/m2-intake-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.}