Merge pull request #366 from sgbett/feat/358-per-gem-specs

refactor: move specs into per-gem directories

Author: sgbett

.claude/plans/20260411-release-skill.md

@@ -0,0 +1,142 @@
+# Plan: `/release` Skill for Gem Releases
+
+**Issue:** #304
+**Previous release pain:** Missing v0.5.0 tag, building from wrong directory, manual changelog
+
+---
+
+## Gem Registry
+
+| Key | Gem name | Version file | Tag prefix | Downstream deps |
+|-----|----------|-------------|------------|-----------------|
+| `sdk` | `bsv-sdk` | `gem/bsv-sdk/lib/bsv/version.rb` | `v` | `bsv-wallet`, `bsv-attest` |
+| `wallet` | `bsv-wallet` | `gem/bsv-wallet/lib/bsv/wallet_interface/version.rb` | `wallet-v` | `bsv-wallet-postgres` |
+| `wallet-postgres` | `bsv-wallet-postgres` | `gem/bsv-wallet-postgres/lib/bsv/wallet_postgres/version.rb` | `wallet-postgres-v` | none |
+| `attest` | `bsv-attest` | `gem/bsv-attest/lib/bsv/attest/version.rb` | `attest-v` | none |
+
+Dependency chain: `bsv-sdk → bsv-wallet → bsv-wallet-postgres`
+
+---
+
+## Release Flow (16 steps)
+
+### Step 0: Hard refusal
+Refuse if user requests releasing multiple gems at once. One at a time only.
+
+### Step 1: Pre-flight checks
+- Dirty working tree → abort
+- Not on master → abort
+- Local master behind origin → abort
+
+### Step 2: Select gem
+From `$ARGUMENTS` or prompt user. Show current versions.
+
+### Step 3: Already-released checks
+- Version already tagged locally → abort
+- Version already on RubyGems (`gem search --remote --exact`) → abort
+
+### Step 4: Choose version bump
+- Gather commits since last tag scoped to `gem/<dir>/`
+- Suggest bump based on conventional commits (`feat!:` → major, `feat:` → minor, else → patch)
+- User confirms or overrides
+
+### Step 5: Downstream dependency check
+Only for gems with downstream dependents (sdk, wallet).
+
+**Part A — Dependency floor check:**
+Read downstream gemspec, check `add_dependency` floor version. Soft warning if floor < new version.
+
+**Part B — Interface compliance check (wallet only):**
+- Extract `def method_name` from `StorageAdapter` (methods raising `NotImplementedError`)
+- Extract `def method_name` from each downstream adapter (all `.rb` files in `lib/`)
+- Report any gaps. Default to abort; user can override.
+
+### Step 6: Generate changelog draft
+- `git log <last_tag>..HEAD -- gem/<dir>/` grouped by conventional commit type
+- Map to Keep a Changelog sections (Added, Fixed, Changed, Breaking, Security)
+- British English throughout
+- Display for user review/edit
+
+### Step 7: Bump version.rb
+Simple string replacement of `VERSION = 'x.y.z'` line.
+
+### Step 8: Update CHANGELOG.md
+Prepend new section after the header, before the first existing `## X.Y.Z` entry.
+
+### Step 9: Commit
+```
+git add gem/<dir>/lib/.../version.rb gem/<dir>/CHANGELOG.md
+git commit -m "chore: release <gem-name> v<version>"
+```
+
+### Step 10: Tag
+`git tag <prefix><version>` using gem's prefix convention.
+
+### Step 11: Push to master (with confirmation)
+```
+git push origin master
+git push origin <tag>
+```
+
+### Step 12: Build gem
+`cd gem/<dir> && gem build <name>.gemspec` (must build from inside gem directory).
+
+### Step 13: Sanity check
+Inspect `.gem` contents — verify `lib/`, `CHANGELOG.md`, `LICENSE` present, no unexpected files.
+
+### Step 14: Prompt user to push to RubyGems
+Skill cannot push — credentials are manual. Display the command and wait for confirmation.
+
+### Step 15: Create GitHub release
+```
+gh release create <tag> --title "<gem-name> <version>" --notes "<changelog>" --target master
+gh release upload <tag> gem/<dir>/<gem-name>-<version>.gem
+```
+
+### Step 16: Summary
+Table with gem, version, tag, commit, RubyGems link, GitHub release link, next steps.
+
+---
+
+## Error Handling
+
+**Hard aborts:** dirty tree, wrong branch, behind origin, already tagged, already on RubyGems, user declines confirmation.
+
+**Soft warnings:** downstream floor not raised, interface compliance failure (default abort, overridable), sanity check anomalies, GitHub release creation failure.
+
+**Recovery guidance:** at every abort, explain what state the release is in and how to continue or roll back.
+
+---
+
+## Rakefile Cleanup
+
+Remove all four `Bundler::GemHelper.install_tasks` lines. The `/release` skill replaces the entire `release[remote]` workflow. Keep `rspec` and `docs:` tasks. Add comment directing to `/release`.
+
+---
+
+## CLAUDE.md Updates
+
+- Update "Releasing Companion Gems" section to reference `/release` as canonical mechanism
+- Document tag prefix conventions for all four gems
+- Fix the `gem build` example in Commands section (currently references old path)
+
+---
+
+## Task Breakdown
+
+1. **Create `.claude/commands/release.md`** — the skill file with full flow
+2. **Clean up Rakefile** — remove unsafe `install_tasks`, add comment
+3. **Update CLAUDE.md** — releasing docs, tag conventions, fix build example
+4. **Manual verification** — dry-run `/release` to test the flow
+
+---
+
+## Risks
+
+| Risk | Mitigation |
+|------|-----------|
+| `gem search --remote` slow/unavailable | Timeout + soft warning |
+| `gh` CLI not authenticated | Check `gh auth status` in pre-flight |
+| No previous tag for a gem (e.g. attest) | Use earliest commit touching `gem/<dir>/` |
+| Interface check false positives (mixins) | Scan all `.rb` files in downstream `lib/` |
+| New gems added to monorepo | Update gem registry in skill file |

.claude/skills/compliance-coverage.md

@@ -0,0 +1,104 @@
+# Cross-SDK Compliance Review
+
+## Problem
+
+During development of the ruby SDK there was a period of time where /effort medium was the default setting.
+
+### Manifestation
+
+The consequences of insufficient effort are several issues that seemed to be due to a lack of rigour when analysing/re-implementing functionality that already exists in the typescript implementation; not recognising *why* some things were done a particular way. Of particular note 3 issues in https://github.com/sgbett/bsv-ruby-sdk/issues/305
+
+The ruby SDK suffered from a systemic issue where we had been able to engineer code that passes all the tests but didn't quite implement the
+desired functionality correctly. We created an SDK that follows "the letter" of the tests, rather than "the spirit" of the specification.
+
+The swift implementation may also have been impacted by the use of /effort medium.
+
+### Solution: The Thirty-Five.
+
+I'd like you to orchestrate a team of agents that is composed of 10 project-level agents, and 8 triumvirates. One triumvirate for each of the 8 phases articulated in the plan /opt/xcode/bsv-sdk/.claude/plans/20260404-swift-bsv-sdk.md - each of these phases broadly scopes an area of concern in the code to focus on. Areas of overlap should be considered carefully as these boundaries likely correspond to the principle of "separation of concerns" we should try to ensure that there are clean lines such that each of the 8 phases cover different areas of the codebase with little to no overlap, A final agent should run alongside and independently audit which triumvirate covered which sections of code to establish any gaps or significant areas of overlap that may warrant refactoring. The triumvirate agents should answer any questions the auditor has, without interference from the project-level agents.
+
+This makes a total of 10 + (8 * 3) + 1 = 35 agents.
+
+## Project Level: 1 x 10 agents
+
+10 "project-level" members based on the specialist definitions in the .architecture/members.yml file these agents are tasked with analysis of the findings reported by the triumverates.
+
+### Findings Analysis
+
+For each finding the 10 project-level team agents should deliberate on what action, if any, should be taken.
+
+The level of agreement determines how the finding should be handled:
+
+* <7 AGREE = SEVERE AMBIGUITY ‼️ - Isolate for seperate examination
+* >7 AGREE = STRONG AGREE ✅ - Recommend action / No-Action, note disagreements
+* ALL AGREE = UNILATERAL - Recommend action / No-Action
+
+Where action is recommended this should be clearly documented as:
+* Problem
+* Proposed Solution
+* Implementation Details
+* Acceptance Crtieria
+
+Where no action is recommended this should be clearly documented as:
+* Potential Issue
+* Reason for no-action
+
+Where ambiguity exists this should be clearly documented as:
+* Potential issues
+* Reasons for action
+* Reasons against action
+* Areas for further exploration
+
+## Triumverates: 8 x 3 agents
+
+For each of the 8 phases there should be a 3 agents with combined responsibility as triumvirate, to validate alignment of our implementation with (in order of precedence):
+* the typescript implementation
+* corresponding BRC's
+* other reference implementation
+* any other documentation, specification discovered ad-hoc that may be relevant
+
+Each triumverate should draw out areas where our deviation may have introduced subtle bugs or incompatibilities. Each "Finding" should be assessed by the project level agents as a group to validate it and confirm the actions to be taken.
+
+### Agent Roles
+
+Within each triumvirate each agent has a specific focus:
+
+#### Agent #phase-#1-dev - A developer, ruby & typescript expert, master of implementation.
+This agent should focus on qualitative difference in implementation between ruby and ts (using go/python as secondary sources) identifying code that needs to be changed and why.
+
+#### Agent #phase-#2-docs - A domain specialist, detail focused, thorough.
+Conduct a deep dive on the documentation and available specifications, seeking out supplementary material on the internet for clarification if needed. The BRC's should be considered authoritative, any other documentation (e.g. in the ts-sdk, or published by the BSVA in their reference docs etc) used to corroborate. This agent should be able to answer any questions any other agent might have on implementation details.
+
+#### Agent #phase-#3-truth - A mediator, logician, a seeker of truth.
+Cross-checks the other two agents work, offering alternative viewpoints, identifying ambiguity between implementation and documentation and surfacing issues. This agent may identify tension or ambiguity that exists in the reference material itself that could lead to misinterpretation - this should be raised as a point of critical concern for resolution before any attempt to resolve.
+
+### The Auditor
+Meticulous, relentless
+By the end of the excercise, this guy knows **exactly** who is responsible for every bit of code.
+
+#### Coverage Flags
+The auditor is seeking to ensure we have cood **Compliance** coverage. This could be considered analagous to test coverage.
+
+**Complaince** is achevied when a triumverates gives attention to the inner workings of "func" calls, particularly where they are checking that this matches the reference implementation, analysis of why code works the way it does.
+**Usage** is when a triumverate looks at code because it needs to now how to use it, what results to expect, but is not concnered with how those results are obtained, or where concern for that is tangential to the momentary anlaysis.
+**Overlap** is where more than one triumverate is looking at code for **Compliance** purposes. **Usage** does not trigger overlap.
+**Gaps** is where no single triumverate looks at code for **Compliance**. **Usage** does not obiate gaps.
+
+Both **Overlap** or **Gaps** may be indicative of an underlying design issue with regards scoping concern, and warrant seperate investigation.
+
+#### Compliance Coverage
+The auditor should produce their own supplementary report on  coverage across the codebase. A high level summary using a traffic light system, three percentage values:
+
+* GREEN: % Compliance
+* YELLOW: % Overlap
+*RED: % Gaps
+
+A very breif summary of Compliance, a single paragraph with key areas covered, followed by detailed sections for each logical cluster of overlap and/or gaps.
+
+The auditor doeas not need validation from the project-level team, their findings should not be veto's they are an independant auditor.
+
+## Summary
+
+Orchestrate as a single team. All agents *can* confer if necessary, but *should* remain focused primilary on their area of concern, within their defined role. 80/20 rules.
+
+This is a complex task, allow all the agents max effort.

.github/workflows/ci.yml

@@ -40,7 +40,7 @@ jobs:
           bundler-cache: true
 
       - name: Run specs
-        run: bundle exec rspec
+        run: bundle exec rake
         env:
           COVERAGE: ${{ matrix.ruby-version == '3.4' && 'true' || '' }}
           DATABASE_URL: postgres://postgres:postgres@localhost:5432/bsv_wallet_test

.rspec

@@ -1,3 +1,2 @@
---require spec_helper
 --format documentation
 --colour