feat(0.17.0): crystallize BROOMVA_ROOT convention (BRO-1223 follow-up)

[broomva]

Summary

Crystallizes the BROOMVA_ROOT env-var convention into bstack as the first cross-cutting workspace convention. Rule-of-three earned across 6 callsites in 3 repos during the BRO-1223 work. The other architectural patterns observed once (LLM-as-index, auto-compact, haystack bench, defensive bounds check) are recorded in the candidate ledger awaiting rule-of-three.

What this PR adds

• references/conventions.md (NEW) — first cross-cutting workspace convention reference. Contains:
  • C1 — BROOMVA_ROOT env-var override: rule + canonical Python + bash patterns; invariant; failure mode prevented (silent overwrite of live workspace); 6 known callsites; BROOMVA_WORKSPACE historical-synonym note
  • Candidate ledger (4 patterns): LLM-as-index architecture, auto-compact catalog, haystack benchmark pattern, defensive post-conversion bounds check — each with status (1 instance) and what's required for promotion
  • How to add a convention section — process for future maintainers
• VERSION — 0.16.0 → 0.17.0 (additive minor bump)
• CHANGELOG.md — 0.17.0 entry

Why a new file (not extending an existing one)

references/primitives.md defines primitive contracts; dogfood-patterns.md defines per-stack validation; stack-architecture.md describes architectural composition. None is the right home for cross-cutting workspace conventions that span all primitives. The new file keeps each reference doc's scope clean.

Rule-of-three audit

The 6 callsites that earned this promotion:

1. ~/.claude/skills/kg/scripts/kg.py (also published as broomva/kg v0.2.x)
2. ~/broomva/skills/bookkeeping/scripts/bookkeeping.py
3. ~/broomva/scripts/bench-kg.py
4. ~/broomva/scripts/bench-kg-haystack.py
5. ~/broomva/scripts/knowledge-catalog-refresh-hook.sh
6. ~/broomva/skills/bookkeeping/tests/test_index.py

Each independently arrived at the same os.environ.get("BROOMVA_ROOT", default) pattern — that's the rule-of-three signal P16 looks for.

What we deliberately did NOT promote

The candidate ledger records 4 BRO-1223-derived patterns at 1 instance each:

• LLM-as-index architecture (substrate → catalog → loader composition)
• Auto-compact catalog at >5000 entities
• Haystack benchmark pattern (synthetic substrate + seeded needles)
• Defensive post-conversion bounds check (R5 floor-to-zero class)

Each will promote to a full convention entry only after 2 more independent instances accumulate. Honors the discipline; avoids over-promotion.

Test plan

• bash scripts/doctor.sh --quiet exits 0 (no behavior change — additive doc)
• references/conventions.md parses as valid markdown
• All 6 listed callsites still match the documented pattern (verified via grep -n "BROOMVA_ROOT" <file>)
• CHANGELOG entry matches commit content

Refs BRO-1223 follow-up. Linear MCP still down — ticket creation deferred.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Added workspace conventions documentation outlining environment variable conventions and workspace-root resolution patterns with implementation examples.
  • Updated changelog with version 0.17.0 release information.

• Chores

  • Bumped version to 0.17.0.

[linear]

BRO-1223

[coderabbitai]

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: e8001019-7142-417d-bfe9-60468e64fed4

📥 Commits

Reviewing files that changed from the base of the PR and between b89354c and 71593e6.

📒 Files selected for processing (3)

• CHANGELOG.md
• VERSION
• references/conventions.md

---

📝 Walkthrough

Walkthrough

This release crystallizes the BROOMVA_ROOT workspace-root convention into a new reference document. The version is bumped from 0.16.0 to 0.17.0, with corresponding changelog and convention documentation introducing canonical patterns for environment-variable–based workspace-root resolution across bstack scripts and skills.

Changes

Convention Crystallization and v0.17.0 Release

Layer / File(s)	Summary
Workspace conventions documentation references/conventions.md, VERSION, CHANGELOG.md	New references/conventions.md defines the mandatory BROOMVA_ROOT workspace-root convention with Python/Bash canonical patterns, invariants, legacy BROOMVA_WORKSPACE synonym, known callsites, and a candidate ledger for future conventions. Version is bumped to 0.17.0, and changelog entry announces this crystallization as a BRO-1223 follow-up.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• broomva/bstack#38: The BROOMVA_ROOT convention crystallized in this PR directly documents the environment variable that PR's bin/bstack-crystallize wrapper uses for default conversations directory selection.

Poem

🐰 A root convention blooms at last so clear,
BROOMVA_ROOT shines bright throughout the year,
With patterns set in Python, Bash, and lore,
The workspace speaks one language more,
Version bumped to mark this grand premiere! 🎉

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/broomva-root-convention

---

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