feat(bootstrap): wire role-x intake + coverage hooks in template

[broomva]

Summary

Closes the gap where bstack bootstrap installed role-x as a skill (via #13 ROSTER) but left its hooks dormant in .claude/settings.json. Every workspace had to wire UserPromptSubmit and the SessionStart coverage entry by hand. After this PR: fresh bstack bootstrap wires both automatically.

What changes

assets/templates/settings.json.snippet (+15 / -1)

• Adds UserPromptSubmit event with role-x-intake-hook.sh (P17 per-prompt routing)
• Extends SessionStart event with role-x-coverage-hook.sh (P17 registry-health nudge, 24h cooldown, silent when fire-rate ≥30%)
• Introduces ${BROOMVA_HOME} placeholder for $HOME-rooted paths (npx skills add -g installs at ${HOME}/.agents/skills/<name>)

scripts/bootstrap.sh (+5 / -2)

• Phase 3 sed substitution: -e flags for both ${BROOMVA_WORKSPACE} and ${BROOMVA_HOME}
• Phase 3 Python merge: two .replace() calls before json.loads()
• Drive-by fix: log printed (PP8) / (PP17) because _bstack_primitive already carries P; now prints (P8) / (P17)

scripts/doctor.sh (+10 / -1)

• §6 hook-wiring array: adds role-x-intake-hook.sh + role-x-coverage-hook.sh with P17 labels
• Pre-existing label fix: skill-freshness-hook.sh P7 (SessionStart) → P8 (SessionStart) (post-feat: align P7/P8/P9 numbering to workspace canonical #16 renumbering)
• Docstring header §5+§6 enumerate the new P17 disk paths

Validation — three dry-run cases on /tmp scratch + live doctor

Case	Setup	Result
A	Fresh scaffold (no existing settings.json)	Snippet renders 5 hook events with absolute paths resolved
B	Existing settings.json with only P1/P2 hooks	Merge adds 4 missing hooks (P8/P17×2/P1); 0 spurious additions
C	Workspace where both role-x hooks are already wired (this one)	Merge does 0 new wires — idempotency confirmed

doctor.sh on this workspace after the edit:

6. .claude/settings.json hook wiring
  [ok] conversation-bridge-hook.sh wired (P1 (Stop, Notification))
  [ok] control-gate-hook.sh wired (P2 (PreToolUse))
  [ok] skill-freshness-hook.sh wired (P8 (SessionStart))
  [ok] role-x-intake-hook.sh wired (P17 (UserPromptSubmit))
  [ok] role-x-coverage-hook.sh wired (P17 (SessionStart))

JSON valid (python3 -c 'json.load(...)'). Bash syntax green on both modified scripts (bash -n).

Coordination with concurrent PRs

• PR fix(polish): SKILL.md body drift + scaffold-and-doctor detector + P20 Linear-ticket #17 (SKILL.md prose drift + AGENTS/CLAUDE templates + scaffold-and-doctor test) touches: SKILL.md, assets/templates/AGENTS.md.template, assets/templates/CLAUDE.md.template, tests/template_lockstep.test.sh. Zero file overlap with this PR.
• SKILL.md ## Hooks section documentation update deferred to a follow-up PR after fix(polish): SKILL.md body drift + scaffold-and-doctor detector + P20 Linear-ticket #17 lands, to keep edits non-overlapping.

Test plan

• JSON valid on new snippet
• Bash syntax green on both modified scripts
• Three dry-run cases (fresh / partial / full)
• doctor.sh on live workspace: 5/5 hook checks [ok]
• No collision with PR fix(polish): SKILL.md body drift + scaffold-and-doctor detector + P20 Linear-ticket #17 (verified via gh pr diff 17)
• Reviewer confirms ${BROOMVA_HOME} placeholder convention (alternative: hard-code $HOME in template; only substitute at write-time)

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added support for additional hook configurations in the settings, enabling new workflow capabilities.

• Documentation

  • Enhanced bootstrap documentation to clarify workspace and home directory variable substitution.

• Bug Fixes

  • Improved variable substitution handling in the bootstrap process for existing configurations.
  • Enhanced validation diagnostics with clearer guidance on resolving missing hook configurations.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 6c96e809-5f01-49b9-bfb5-14ff41482fdd

📥 Commits

Reviewing files that changed from the base of the PR and between df06ea3 and 5b9f0b5.

📒 Files selected for processing (3)

• assets/templates/settings.json.snippet
• scripts/bootstrap.sh
• scripts/doctor.sh

---

📝 Walkthrough

Walkthrough

Settings template extended with two new role-x hooks (coverage and intake) wired to SessionStart and UserPromptSubmit. Bootstrap script updated to substitute both workspace and home variables. Doctor script expanded to validate and guide the new hook configuration.

Changes

Role-X Hook Integration

Layer / File(s)	Summary
New Hook Definitions in Settings Template assets/templates/settings.json.snippet	Documentation expanded to describe variable substitution behavior, and two new role-x command hooks added with timeouts and P17 primitive markers: role-x-coverage-hook.sh for hooks.SessionStart and role-x-intake-hook.sh for hooks.UserPromptSubmit.
Bootstrap Variable Substitution scripts/bootstrap.sh	Both ${BROOMVA_WORKSPACE} and ${BROOMVA_HOME} are now substituted in the template during sed preprocessing and Python JSON merge. Hook merge log output changed to format _bstack_primitive as ({value}) with default P?.
Doctor Script Validation and Guidance scripts/doctor.sh	Hook wiring documentation updated to list the two new role-x scripts, HOOK_FILES extended with role-x-intake-hook.sh and role-x-coverage-hook.sh, HOOK_LABELS updated to reflect additional P17 expectations, and missing-hook remediation message refined to reference AGENTS.md spec and suggest bstack repair/bstack bootstrap.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related PRs

• broomva/bstack#4: Aligned updates to the scaffold/wire/doctor pipeline for hook template definition, bootstrap variable substitution, and doctor-based hook wiring verification.

Poem

Hooks on hooks, the coverage grows,
Role-X takes flight where freshness flows. 🐰
Bootstrap weaves the variables tight,
Doctor validates with all its might,
New primitives dance in the morning light! ✨

✨ 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/bootstrap-role-x-hooks

---

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.}