fix(bstack): fresh-install portability — un-dangle the self-improving/autonomy layer (BRO-1715)

[broomva]

What & why

bstack's discipline harness transplanted cleanly to a fresh non-~/broomva workspace, but its self-improving / autonomy layer was silently ~/broomva-hosted. Four packaging bugs made a fresh git clone bstack && bstack bootstrap install look healthy while the control loop was dead on arrival — the all-green in ~/broomva is a self-hosting artifact (~/broomva is the bstack monorepo, so it's the one workspace that passes vacuously).

Fixes BRO-1715. Packaging only — no primitive added, no governance rule changed.

The four bugs (all re-confirmed on disk, RED-tested before fix)

#	Bug	Fix
1	5 loop/autonomy hooks (bstack-autoupdate, knowledge-wakeup — the loop actuation wire, auth-preflight, autonomous-posture, arc-continuation) wired at ${BROOMVA_HOME}/.claude/skills/bstack/scripts/ — a dir no install step creates (bstack installs by git-clone, never npx skills add). All 5 dangled; the BRO-1707 ship-signal that rides knowledge-wakeup died with them.	Re-rooted all 5 at $BSTACK_REPO/scripts/ (where their SELF_DIR siblings leverage-sensor.py/leverage-ship-sensor.py/autonomous-arc.sh co-locate; the same substitution install-rcs-stability.sh already bakes). bootstrap.sh Phase 3 and repair.sh (which duplicates the snippet merge) now substitute $BSTACK_REPO.
2	.control/leverage-setpoints.yaml (reference r0) never seeded → leverage-sensor.py ran referenceless (empty metrics); doctor §23 could never certify closure.	bootstrap.sh Phase 2 scaffolds it (idempotent, never overwrites, authored_by: bstack-default left for the human to sign).
3	doctor §7 false-RED: checked workspace-relative skills/<n>/scripts/*.py, but P6/P9/P12 install globally (-g → ~/.claude/skills + ~/.agents/skills).	§7 now also resolves the global skill dirs (mirrors the existing /kg check).
4	doctor false-GREEN off-broomva: WORKSPACE defaulted to $HOME/broomva, so a bare bstack doctor from an unrelated dir audited the healthy ~/broomva.	Resolves via the shared scripts/lib/resolve-workspace.sh (env → cwd-is-workspace → ~/.bstack config → cwd); fails loud (exit 3) on a non-workspace rather than defaulting.

New

• doctor §25 — Wired hook command resolution. Every wiring check greps that a hook is wired by name (§24-style) but never that its command resolves — exactly how Bug 1 stayed silent. §25 resolves every wired command (conservative shlex-based absolute-path extraction; hard-gaps a bstack-shipped dangle, soft-infos a not-yet-installed companion skill).
• tests/fresh-install-portability.test.sh — hermetic (no network/gh, isolated $HOME). Bootstraps into an empty scratch workspace; 6 assertions, RED-before / GREEN-after.

Validation

• New test 6/6; full tests/*.test.sh suite 33/33 + canary 5/5; shellcheck clean; snippet valid JSON.
• ~/broomva doctor 102/102 (a first §25 draft false-positived on the python3 <script> Stop hook — fixed with interpreter/quote-aware extraction).
• P20 cross-review: 8/10 (fresh-context adversarial pass — substitution correctness incl. the quoted-vs-unquoted heredoc asymmetry, exit-3 regression containment across all callers, test honesty, idempotency all independently verified). Codex/Strata-A unavailable (usage limit). §25 hardened per the reviewer's finding feat(bstack): add bstack doctor — verify primitive contract #2.

Migration

Existing installs: re-run bstack repair to re-root the 5 hooks + seed leverage-setpoints.yaml. A workspace whose live settings.json still carries the old ~/.claude/skills/bstack/scripts/ paths will now surface them as §25 hard gaps (a true finding — those hooks were dead).

Known follow-up (out of scope)

• P8 branch-janitor.sh is not in bootstrap.sh's WORKSPACE_HOOKS deploy list and isn't a skills/ path, so fresh installs still show "P8 mechanism missing" (pre-existing).
• Some other suite tests bootstrap into \$PWD and leak scaffold artifacts (METALAYER.md, schemas/*.schema.json) into the repo root — a test-hygiene follow-up, not touched here.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved fresh-install portability when using a workspace outside the default location.
  • Fixed setup and diagnostic checks so they correctly find hooks and skills in more environments, including globally installed ones.
  • Doctor checks now fail clearly when run outside a valid workspace instead of silently passing.
  • Resolved issues with hook commands so missing or broken paths are reported more accurately.

• Tests

  • Added a new end-to-end test covering fresh installs and portable workspace behavior.

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: b7da38bf-5339-42de-a618-ffcf629fa098

📥 Commits

Reviewing files that changed from the base of the PR and between 8e90631 and 0e9b0fe.

📒 Files selected for processing (7)

• CHANGELOG.md
• VERSION
• assets/templates/settings.json.snippet
• scripts/bootstrap.sh
• scripts/doctor.sh
• scripts/repair.sh
• tests/fresh-install-portability.test.sh

---

📝 Walkthrough

Walkthrough

This PR fixes fresh-install portability for the bstack self-improving/autonomy layer when installed outside ~/broomva. Hook paths in the settings template now use a $BSTACK_REPO placeholder substituted during bootstrap/repair; doctor.sh gains stricter workspace resolution, global-skill-aware mechanism checks, and a new wired-hook-command resolution section; a hermetic regression test and changelog/version bump are added.

Changes

Fresh-install portability fix

Layer / File(s)	Summary
Hook path templating assets/templates/settings.json.snippet	SessionStart, UserPromptSubmit, and Stop hook commands switched from ${BROOMVA_HOME}/.claude/skills/bstack/scripts/… to $BSTACK_REPO/scripts/…, with updated template comments.
Bootstrap/repair placeholder substitution and governance scaffolding scripts/bootstrap.sh, scripts/repair.sh	Bootstrap and repair scaffolding/merge logic substitute $BSTACK_REPO with the resolved skill root before generating or merging .claude/settings.json; bootstrap also scaffolds .control/leverage-setpoints.yaml idempotently.
Doctor workspace resolution and gap detection scripts/doctor.sh	Workspace resolution now uses a shared resolver and hard-fails (exit 3) on invalid workspaces instead of silently defaulting to ~/broomva; skill mechanism checks search global install roots; new Section 25 validates wired hook commands resolve to existing scripts, reporting hard gaps or informational misses.
Fresh-install portability regression test tests/fresh-install-portability.test.sh	New hermetic test harness runs bootstrap in an isolated temp workspace/HOME and asserts hook path resolution, leverage-setpoints content, no false-RED for globally installed skills, hard failure on non-workspace directories, tolerance for composite hook commands, and detection of dangling hook paths.
Changelog and version bump CHANGELOG.md, VERSION	Adds the 0.34.0 release notes describing the fix and migration step, and bumps version from 0.33.0 to 0.34.0.

Estimated code review effort: 3 (Moderate) | ~30 minutes

Sequence Diagram(s)

sequenceDiagram
  participant bootstrap.sh
  participant repair.sh
  participant settingsSnippet as settings.json.snippet
  participant settingsJson as .claude/settings.json
  participant doctor.sh
  bootstrap.sh->>settingsSnippet: read template with $BSTACK_REPO placeholder
  bootstrap.sh->>settingsJson: substitute $BSTACK_REPO with SKILL_ROOT and merge
  repair.sh->>settingsJson: substitute $BSTACK_REPO and merge/scaffold hooks
  doctor.sh->>settingsJson: parse wired hook commands
  doctor.sh->>doctor.sh: resolve workspace, validate .git/.control
  doctor.sh->>doctor.sh: check skill paths under global roots
  doctor.sh-->>bootstrap.sh: report gaps (hard/info) or ok

Loading

Possibly related PRs

• broomva/bstack#86: Both PRs update workspace resolution via scripts/lib/resolve-workspace.sh and change doctor.sh/bootstrap behavior for fresh installs.
• broomva/bstack#19: Both PRs modify assets/templates/settings.json.snippet/scripts/bootstrap.sh hook wiring and extend scripts/doctor.sh validation of wired hooks.
• broomva/bstack#2: Both PRs extend scripts/doctor.sh governance/primitive-contract validation at the same code entry points.

✨ 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 bro-1715-fresh-install-portability

---

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