release: v0.2.3 — merge develop into main

Author: tbitcs

.github/workflows/dev-release.yml

@@ -41,14 +41,12 @@ jobs:
 
       - name: Set dev version
         run: |
-          # Read base version and bump patch for dev
+          # Use pyproject.toml version as the base (no patch bump).
+          # pyproject.toml should always hold the NEXT release version (e.g. 0.2.3).
+          # Dev builds publish as 0.2.3.devN — PEP 440 pre-release of the upcoming release.
           BASE_VERSION=$(grep 'version = ' pyproject.toml | head -1 | sed 's/version = "\(.*\)"/\1/')
-          MAJOR=$(echo $BASE_VERSION | cut -d. -f1)
-          MINOR=$(echo $BASE_VERSION | cut -d. -f2)
-          PATCH=$(echo $BASE_VERSION | cut -d. -f3)
-          NEXT_PATCH=$((PATCH + 1))
           COMMIT_COUNT=$(git rev-list --count HEAD ^$(git describe --tags --abbrev=0 2>/dev/null || echo HEAD~100) 2>/dev/null || echo 0)
-          DEV_VERSION="${MAJOR}.${MINOR}.${NEXT_PATCH}.dev${COMMIT_COUNT}"
+          DEV_VERSION="${BASE_VERSION}.dev${COMMIT_COUNT}"
           echo "DEV_VERSION=${DEV_VERSION}" >> $GITHUB_ENV
 
           # Patch pyproject.toml with dev version

CHANGELOG.md

@@ -7,6 +7,19 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.3] - 2026-04-03
+
+### Fixed
+- **Governance RTD table rendering** (#55): rows 2–6 of the Modular Governance table in `docs/site/governance.md` started with `||` instead of `|`, breaking layout. Introduced during the uppercase filename migration.
+
+### Added
+- **RTD commands page complete** (#56): `docs/site/commands.md` now documents all 40+ commands — previously 13 of 40+ were documented. Added sections for `exec`/`ps`/`abort`, `commit`/`push`/`sync`/`branch`/`pr`, `session-end`, `update`, `apply`, `migrate-project`, `release`, `verify-release`, `ledger add/list/stats`, `req list/add/trace/gaps/orphans`, `plugin`, `serve`, and `credits limits`.
+- **H11/H12 governance rules and blocking-loop enforcement** (#58): two new hard rules added to the `RULES.md` governance template. H11 requires every loop or blocking wait in agent-written scripts to have a deadline, fallback exit, and diagnostic message. H12 requires Windows multi-step automation to use `.cmd` files. `specsmith validate` now scans `.sh`/`.cmd`/`.ps1`/`.bash` files under `scripts/` and the project root and flags infinite-loop patterns without a recognised deadline/timeout guard.
+- **Proactive per-model rate-limit pacing** (#59): `BUILTIN_PROFILES` constant ships conservative RPM/TPM defaults for OpenAI (gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-3.5-turbo, o1, o1-mini, o3-mini, gpt-5.4, wildcard), Anthropic (claude-opus-4, claude-sonnet-4, claude-haiku-3-5, claude-3-5-sonnet, wildcard), and Google (gemini-1.5-pro, gemini-1.5-flash, gemini-2.0-flash, gemini-2.5-pro, wildcard). Two new `credits limits` subcommands: `status` (rolling-window RPM/TPM/concurrency snapshot) and `defaults` (list or `--install` built-in profiles). Local overrides always take precedence over built-ins.
+- **Rate Limit Pacing RTD page**: new `docs/site/rate-limits.md` documents the scheduler model, built-in profiles table, CLI commands, persistent state, and the Python API.
+- **README updated**: new sections for Governance Rules (H11/H12) and Proactive Rate Limit Pacing with RTD links. Commands table expanded to all major command groups.
+- **Dev release CI fixed**: workflow now uses `pyproject.toml` version directly (no patch bump) so dev builds publish as `0.2.3.devN` — PEP 440 compliant pre-releases of the upcoming stable version.
+
 ## [0.2.2] - 2026-04-02
 
 ### Fixed
@@ -194,7 +207,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **G9**: Session start file list now marks services.md as conditional ("if it exists").
 - **G10**: Open TODOs format specified as `- [ ]` / `- [x]` checkbox syntax.
 
-[Unreleased]: https://github.com/BitConcepts/specsmith/compare/v0.2.2...HEAD
+[Unreleased]: https://github.com/BitConcepts/specsmith/compare/v0.2.3...HEAD
+[0.2.3]: https://github.com/BitConcepts/specsmith/compare/v0.2.2...v0.2.3
 [0.2.2]: https://github.com/BitConcepts/specsmith/compare/v0.2.1...v0.2.2
 [0.2.1]: https://github.com/BitConcepts/specsmith/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/BitConcepts/specsmith/compare/v0.1.3...v0.2.0

LEDGER.md

@@ -35,7 +35,37 @@ Estimated cost: high
 - CI: lint ✓, security ✓, typecheck pending (fix pushed)
 
 ### Open TODOs
-- [ ] Add VCS platform integrations (GitHub/GitLab/Bitbucket CLI)
-- [ ] Add Gemini, Windsurf, Aider agent adapters
-- [ ] Expand CLI runner test coverage
-- [ ] Self-host governance (this file)
+- [x] Add VCS platform integrations (GitHub/GitLab/Bitbucket CLI)
+- [x] Add Gemini, Windsurf, Aider agent adapters
+- [x] Expand CLI runner test coverage
+- [x] Self-host governance (this file)
+
+## Session 2026-04-02 — v0.2.0→v0.2.2 release cycle
+
+**Status:** Complete
+**Scope:** Major feature release + two patch releases
+
+### Changes
+- **v0.2.0**: Uppercase governance filenames, community templates (#42), AI credit tracking (#50/#51), architect command (#49), self-update, multi-language detection, dynamic versioning, VCS commands, ledger/req/test CLIs, plugin scaffold
+- **v0.2.1**: Process abort/PID tracking (exec/ps/abort commands), language-specific templates (#41 — Rust, Go, JS/TS), RTD integration (#38), release workflow templates (#44), PyPI integration (#36), template refactor (#45), upgrade --full sync mechanism
+- **v0.2.2**: Auto-fix AGENTS.md references on lowercase→uppercase migration, alternate path detection (docs/LEDGER.md, docs/architecture/**), case-insensitive architecture check, CI-gated dev releases
+
+### Issues closed
+- #36, #38, #41, #42, #44, #45 (closed), #55, #56 (filed)
+- Created v0.3.0 milestone, assigned 6 remaining issues
+
+### Verification
+- 115 tests passing (pytest, 3 OS × 3 Python)
+- ruff check + format: clean (src/ + tests/)
+- mypy strict: clean
+- CI: 19/19 checks pass on all PRs before merge
+- CodeQL: 0 open alerts
+- Dependabot: 0 open alerts
+
+### Open TODOs
+- [ ] #55: Fix governance table rendering on RTD (double pipe)
+- [ ] #56: Document 15+ missing CLI commands in RTD
+- [ ] #52: Credit budget cap enforcement
+- [ ] #37: Secure API key management
+- [ ] #10: USPTO/MCP patent integration
+- [ ] #17: Multi-project workspace management

README.md

@@ -86,15 +86,21 @@ Each type gets: tool-aware CI (correct lint/test/security/build tools), domain-s
 | `import` | Adopt an existing project (merge mode) |
 | `audit` | Drift detection and health checks (`--fix` to auto-repair) |
 | `architect` | Interactive architecture generation |
-| `validate` | Governance file consistency checks |
+| `validate` | Governance consistency + H11 blocking-loop detection |
 | `compress` | Archive old ledger entries |
 | `upgrade` | Update governance to new spec version |
 | `status` | CI/PR/alert status from VCS platform |
 | `diff` | Compare governance against templates |
 | `export` | Compliance report with REQ↔TEST coverage |
 | `doctor` | Check if verification tools are installed |
 | `self-update` | Update specsmith (channel-aware) |
-| `credits` | AI credit tracking, analysis, and budgets |
+| `credits` | AI credit tracking, analysis, budgets, and rate-limit pacing |
+| `exec` / `ps` / `abort` | Tracked process execution with PID tracking and timeout |
+| `commit` / `push` / `sync` | Governance-aware VCS operations |
+| `branch` / `pr` | Strategy-aware branching and PR creation |
+| `ledger` | Structured ledger add/list/stats |
+| `req` | Requirements list/add/trace/gaps/orphans |
+| `session-end` | End-of-session checklist |
 
 ## 7 Agent Integrations
 
@@ -104,9 +110,36 @@ AGENTS.md (cross-platform standard), Warp/Oz, Claude Code, GitHub Copilot, Curso
 
 GitHub Actions, GitLab CI, Bitbucket Pipelines — all with tool-aware CI generated from the verification tool registry. Dependabot/Renovate configured per language ecosystem.
 
+## Governance Rules (H1–H12)
+
+specsmith-governed projects enforce 12 hard rules. Two were added in v0.2.3 for agentic workflows:
+
+- **H11** — Every loop or blocking wait in agent-written scripts must have a deadline, a fallback exit, and a diagnostic message on timeout. `specsmith validate` enforces this automatically.
+- **H12** — On Windows, multi-step automation goes into a `.cmd` file, not inline shell invocations or `.ps1` files.
+
+See [Governance Model](https://specsmith.readthedocs.io/en/stable/governance/) for the full rule set.
+
+## Proactive Rate Limit Pacing
+
+specsmith ships a rolling-window scheduler that paces AI provider requests before dispatch:
+
+- Built-in RPM/TPM profiles for OpenAI, Anthropic, and Google models (including wildcard fallbacks)
+- Pre-dispatch budget check: sleeps until the 60-second window refills instead of overshooting
+- Parses OpenAI-style `"Please try again in 10.793s"` messages and obeys them
+- Adaptive concurrency: halved after a 429, gradually restored after consecutive successes
+- Local overrides always take precedence over built-in defaults
+
+```bash
+specsmith credits limits defaults          # list built-in profiles
+specsmith credits limits defaults --install  # merge into project config
+specsmith credits limits status --provider openai --model gpt-5.4
+```
+
+See [Rate Limit Pacing](https://specsmith.readthedocs.io/en/stable/rate-limits/) for full details.
+
 ## Documentation
 
-**[specsmith.readthedocs.io](https://specsmith.readthedocs.io)** — Full user manual with tutorials, command reference, project type details, tool registry, governance model, troubleshooting.
+**[specsmith.readthedocs.io](https://specsmith.readthedocs.io)** — Full user manual with tutorials, command reference, project type details, tool registry, governance model, rate-limit pacing, troubleshooting.
 
 ## Links