feat(bstack): add bstack doctor — verify primitive contract

[broomva]

Summary

Adds `bstack doctor` — a companion to the upcoming P10 (Worktree Hygiene Discipline) primitive in broomva/workspace#42.

When bstack is installed, the skill should make sure the workspace's governance files (`AGENTS.md`, `CLAUDE.md`, `.control/policy.yaml`, `.claude/settings.json`) properly comply with the whole stack's primitive contract. `bstack doctor` is that mechanism.

Files

• `scripts/doctor.sh` (~190 LOC) — Bash 3.2 compatible (no associative arrays). Seven check sections, ~39 individual checks total.
• `SKILL.md` — new `doctor` command section between `validate` and `revamp`.
• `scripts/bootstrap.sh` — invokes `doctor --quiet` as final step. Skill count 27 → 30 (matches current roster).

What the doctor checks

#	Section	What
1	Governance files	CLAUDE.md, AGENTS.md, .control/policy.yaml exist
2	CLAUDE.md primitives table	All P1–P10 rows + correct count header ("Ten irreducible…")
3	AGENTS.md primitive sections	`### P1:` through `### P10:`
4	Reflexive Trigger Rules	Present for P6, P7, P10 (the reasoning-enforced primitives)
5	policy.yaml blocks	`ci_watch:`, `ci_heal:`, `auto_merge:` present
6	Settings hooks wired	P1, P2, P8 hook scripts referenced in `.claude/settings.json`
7	Primitive mechanisms	Each script/skill reachable on disk

Modes

• default — full passes/gaps report with `→ fix:` hints; exit 0 (always non-blocking)
• `--quiet` — only show gaps (used by bootstrap; minimal output when healthy)
• `--strict` — exit 1 on any gap (CI mode)

Smoke test

Run locally on a workspace that hasn't yet pulled broomva/workspace#42:

```
[bstack doctor] 35/39 passed, 4 gap(s) — see above

• primitive count header off (expected 'Ten irreducible'; saw 'Nine irreducible')
• P10 row missing in primitives table
• AGENTS.md missing '### P10: Worktree Hygiene' section
• P10 section in AGENTS.md missing 'Reflexive Trigger Rule' subsection
  ```

Caught exactly the 4 expected P10 gaps. After workspace#42 lands, doctor will report 39/39.

Order of merges

This PR + workspace#42 (P10 governance) ship together. Recommended order:

1. workspace#42 (governance) merges first — adds P10 to CLAUDE.md/AGENTS.md
2. bstack#this merges second — doctor is now satisfied by the new governance
3. `npx skills update -g` propagates the new bstack to existing installs

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Added a new doctor command to verify governance compliance and contract requirements across your workspace.
  • Bootstrap process now automatically runs doctor verification as the final step.
  • Generates comprehensive validation reports identifying gaps in governance setup.
  • Provides actionable fix guidance for identified gaps.
  • Supports quiet and strict CI modes for different workflow needs.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR introduces a new doctor command that validates governance files (CLAUDE.md, AGENTS.md, .control/policy.yaml, .claude/settings.json) and primitive mechanisms against workspace contract requirements. The doctor script is integrated into bootstrap as a final verification step and documented in the command reference.

Changes

Governance Validation Feature

Layer / File(s)	Summary
Documentation SKILL.md	New doctor command documented under Commands section, describing validation checks, output modes (--quiet, --strict), and automatic invocation by bootstrap.
Core Implementation scripts/doctor.sh	Complete validation script with helpers (ok(), gap(), section()). Performs seven sequential checks across governance files presence, CLAUDE.md primitives table structure, AGENTS.md sections P1–P10, reflexive trigger rules, policy.yaml blocks, Claude hook wiring, and on-disk primitive mechanisms. Reports gaps with fixes; exits 0 by default, 1 in strict CI mode.
Bootstrap Integration scripts/bootstrap.sh	Integrates doctor as final bootstrap step in quiet mode. Updates item count from 27 to 30 and adds conditional execution of doctor.sh if present.

Estimated Code Review Effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 A doctor hops through governance halls,
Checking primitives beyond the walls,
P1 to P10, each gap it finds,
With nudges gentle and fixes kind—
Bootstrap's final guardian, ever keen! 🏥✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'feat(bstack): add bstack doctor — verify primitive contract' accurately and directly describes the main change: introducing a new bstack doctor command for verifying the primitive contract.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ 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/bstack-doctor

---

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

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

scripts/bootstrap.sh (1)

88-88: ⚡ Quick win

Derive total from roster instead of hardcoding 30

Line 88 will drift if skills are added/removed again. Prefer ${#ORDERED_SKILLS[@]} for an always-correct total.

Suggested fix

-echo "  Total: $((installed + skipped))/30"
+echo "  Total: $((installed + skipped))/${`#ORDERED_SKILLS`[@]}"

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/bootstrap.sh` at line 88, The summary count uses a hardcoded 30;
update the echo to derive the total from the roster by replacing the hardcoded
30 with the length of ORDERED_SKILLS (use ${`#ORDERED_SKILLS`[@]} or a computed
total variable) so the displayed total reflects the actual number of skills;
adjust the echo line that references installed and skipped (and any related
variable named ORDERED_SKILLS, installed, skipped) to use ${`#ORDERED_SKILLS`[@]}
for the denominator.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@scripts/doctor.sh`:
- Around line 47-49: The workspace existence check in scripts/doctor.sh uses -d
for "$WORKSPACE/.git" which fails for Git worktrees where .git is a file; update
the conditional that references WORKSPACE to treat .git as either a file or
directory (e.g., test for existence with -e or combine -d || -f) so the check
becomes: if neither "$WORKSPACE/.git" nor "$WORKSPACE/.control" exist, then
print the message and exit. Modify the conditional guarding that echo/exit block
(the one referencing WORKSPACE, "$WORKSPACE/.git" and "$WORKSPACE/.control")
accordingly.

---

Nitpick comments:
In `@scripts/bootstrap.sh`:
- Line 88: The summary count uses a hardcoded 30; update the echo to derive the
total from the roster by replacing the hardcoded 30 with the length of
ORDERED_SKILLS (use ${`#ORDERED_SKILLS`[@]} or a computed total variable) so the
displayed total reflects the actual number of skills; adjust the echo line that
references installed and skipped (and any related variable named ORDERED_SKILLS,
installed, skipped) to use ${`#ORDERED_SKILLS`[@]} for the denominator.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 1ee8be61-9d74-433c-821a-a4cbefd50537

📥 Commits

Reviewing files that changed from the base of the PR and between 3376bb9 and 530f32e.

📒 Files selected for processing (3)

• SKILL.md
• scripts/bootstrap.sh
• scripts/doctor.sh

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

Workspace detection misses valid Git worktrees (false “not found”)

Line 47 checks .git with -d, but in worktrees .git is a file. That can make doctor exit early on valid workspaces and skip all checks.

Suggested fix

-if [ ! -d "$WORKSPACE/.git" ] && [ ! -d "$WORKSPACE/.control" ]; then
+if [ ! -e "$WORKSPACE/.git" ] && [ ! -d "$WORKSPACE/.control" ]; then
     echo "[bstack doctor] workspace not found at $WORKSPACE (set BROOMVA_WORKSPACE)"
     exit 0
 fi

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	if [ ! -d "$WORKSPACE/.git" ] && [ ! -d "$WORKSPACE/.control" ]; then
	echo "[bstack doctor] workspace not found at $WORKSPACE (set BROOMVA_WORKSPACE)"
	exit 0
	if [ ! -e "$WORKSPACE/.git" ] && [ ! -d "$WORKSPACE/.control" ]; then
	echo "[bstack doctor] workspace not found at $WORKSPACE (set BROOMVA_WORKSPACE)"
	exit 0
	fi

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@scripts/doctor.sh` around lines 47 - 49, The workspace existence check in
scripts/doctor.sh uses -d for "$WORKSPACE/.git" which fails for Git worktrees
where .git is a file; update the conditional that references WORKSPACE to treat
.git as either a file or directory (e.g., test for existence with -e or combine
-d || -f) so the check becomes: if neither "$WORKSPACE/.git" nor
"$WORKSPACE/.control" exist, then print the message and exit. Modify the
conditional guarding that echo/exit block (the one referencing WORKSPACE,
"$WORKSPACE/.git" and "$WORKSPACE/.control") accordingly.