feat: issues #55 #56 #58 #59 — RTD table fix, commands docs, H11/H12 rules, rate-limit pacing

- fix(#55): governance.md Modular Governance table rows 2-6 started
  with || instead of | (duplicate pipe from uppercase migration)
- docs(#56): commands.md now covers all 40+ commands — previously only
  13 of 40+ were documented; added exec/ps/abort, commit/push/sync,
  branch/pr, session-end, update, apply, migrate-project, release,
  verify-release, ledger, req, plugin, serve, credits limits
- feat(#58): H11 (no unbounded loops/blocking I/O without deadline)
  and H12 (Windows .cmd files for multi-step automation) added to
  rules.md.j2 governance template; specsmith validate now scans
  .sh/.cmd/.ps1/.bash script files for infinite-loop patterns without
  a recognised deadline/timeout guard
- feat(#59): BUILTIN_PROFILES constant ships conservative RPM/TPM
  defaults for OpenAI, Anthropic, Google (20 entries + wildcard
  fallbacks); new credits limits status and credits limits defaults
  CLI subcommands; RTD rate-limits.md page; README updated

Co-Authored-By: Oz <oz-agent@warp.dev>

Author: tbitcs

CHANGELOG.md

@@ -7,7 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
-## [0.2.2] - 2026-04-02
+### 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.
+
+## [0.2.2]
 
 ### Fixed
 - **Upgrade auto-fixes AGENTS.md references**: when `upgrade` renames governance files (lowercase→uppercase), it now rewrites path references in AGENTS.md, CLAUDE.md, GEMINI.md, SKILL.md, and all agent config files automatically.

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
 

docs/site/commands.md

@@ -208,6 +208,268 @@ specsmith credits budget --cap 50 --alert-pct 80         # Set budget
 
 Credit data stored locally at `.specsmith/credits.json` (gitignored).
 
+## `specsmith exec`
+
+Execute a command with PID tracking and timeout enforcement.
+
+```bash
+specsmith exec "pytest tests/" --timeout 300
+specsmith exec "make build" --timeout 120 --project-dir ./my-project
+```
+
+**Options:**
+
+- `--timeout INT` — Maximum seconds to wait (default: 120). Process is killed when deadline fires.
+- `--project-dir PATH` — Project root (default: `.`). PID and log files go under `.specsmith/`.
+
+Tracks the process in `.specsmith/pids/<pid>.json` and logs stdout/stderr to `.specsmith/logs/`. Works on Windows (taskkill), Linux, and macOS (SIGTERM → SIGKILL).
+
+**Exit codes:** Mirrors the child process exit code. Returns 124 on timeout.
+
+## `specsmith ps`
+
+List tracked running processes.
+
+```bash
+specsmith ps --project-dir ./my-project
+```
+
+Shows PID, time remaining to timeout, and command for every tracked process. Prunes stale PID files for processes that already exited.
+
+## `specsmith abort`
+
+Kill tracked process(es).
+
+```bash
+specsmith abort --pid 12345
+specsmith abort --all
+```
+
+**Options:**
+
+- `--pid INT` — Kill a specific tracked PID.
+- `--all` — Kill every tracked process.
+
+Without `--pid` or `--all`, prints the current process list and instructions.
+
+## `specsmith commit`
+
+Governance-aware commit: checks ledger, optionally audits, then commits.
+
+```bash
+specsmith commit -m "feat: add export command"
+specsmith commit --no-audit --auto-push
+```
+
+**Options:**
+
+- `-m / --message TEXT` — Override the commit message (default: last ledger entry heading).
+- `--no-audit` — Skip the pre-commit audit check.
+- `--auto-push` — Push after a successful commit.
+
+Warns if `LEDGER.md` was not updated since the last commit.
+
+## `specsmith push`
+
+Push the current branch with safety checks.
+
+```bash
+specsmith push
+specsmith push --force
+```
+
+**Options:**
+
+- `--force` — Skip branch-protection checks.
+
+## `specsmith sync`
+
+Pull latest and warn about governance conflicts.
+
+```bash
+specsmith sync --project-dir ./my-project
+```
+
+Runs `git pull` and checks for conflicts in governance files (AGENTS.md, LEDGER.md, docs/governance/*).
+
+## `specsmith branch`
+
+Strategy-aware branch management.
+
+```bash
+specsmith branch create feature/my-feature
+specsmith branch list
+```
+
+**Subcommands:**
+
+- `create NAME` — Create a branch following the configured branching strategy (gitflow / trunk-based / GitHub Flow). Reads strategy from `scaffold.yml`.
+- `list` — List branches with their role annotation (main, develop, feature, hotfix, etc.).
+
+## `specsmith pr`
+
+Create a PR with governance context in the body.
+
+```bash
+specsmith pr --title "Add export command"
+specsmith pr --draft
+```
+
+**Options:**
+
+- `--title TEXT` — PR title.
+- `--draft` — Create as a draft PR.
+
+Appends the first 2000 characters of `specsmith export` output to the PR body. Requires `gh` (GitHub), `glab` (GitLab), or `bb` (Bitbucket) CLI.
+
+## `specsmith session-end`
+
+Run the end-of-session checklist.
+
+```bash
+specsmith session-end --project-dir ./my-project
+```
+
+Checks: uncommitted changes, ledger updated, open TODOs count, audit health. Reports items that need action before ending the session.
+
+## `specsmith update`
+
+Check for updates and optionally install the latest version + migrate the project.
+
+```bash
+specsmith update
+specsmith update --check            # Check only, don't install
+specsmith update --yes              # Skip confirmation prompt
+```
+
+**Options:**
+
+- `--check` — Print available version and exit without installing.
+- `--yes` — Auto-confirm update and migration prompts.
+
+Auto-detects channel (stable vs dev) from the installed version. Runs `migrate-project` if the project scaffold needs migration after the update.
+
+## `specsmith apply`
+
+Regenerate CI and agent integration files from the current `scaffold.yml`.
+
+```bash
+specsmith apply --project-dir ./my-project
+```
+
+Re-renders GitHub Actions / GitLab CI / Bitbucket Pipelines config and agent integration files (CLAUDE.md, GEMINI.md, `.warp/`, etc.). Safe: never overwrites AGENTS.md, LEDGER.md, or user-authored docs.
+
+## `specsmith migrate-project`
+
+Migrate project scaffold to the current specsmith version.
+
+```bash
+specsmith migrate-project --project-dir ./my-project
+specsmith migrate-project --dry-run
+```
+
+**Options:**
+
+- `--dry-run` — Show what would change without writing.
+
+## `specsmith release`
+
+Bump the version string everywhere and scan for stale references.
+
+```bash
+specsmith release 0.3.0
+specsmith release 0.3.0 --project-dir ./my-project
+```
+
+Updates version in `pyproject.toml`, `Cargo.toml`, `package.json`, `src/**/__init__.py`, README badges, and CHANGELOG. Scans for references to the old version that may need updating. Prints the next manual steps (CHANGELOG, git tag, push).
+
+## `specsmith verify-release`
+
+Post-release smoke check: verify PyPI, RTD, and GitHub release are live.
+
+```bash
+specsmith verify-release
+```
+
+Checks that the installed version is published on PyPI, that the RTD site is reachable, and that the GitHub Release tag exists. Requires `gh` CLI for the GitHub check.
+
+## `specsmith ledger`
+
+Structured ledger management.
+
+```bash
+specsmith ledger add "Implemented export command" --type feature --reqs REQ-CLI-005
+specsmith ledger list --since 2026-03-01
+specsmith ledger stats
+```
+
+**Subcommands:**
+
+- `add DESCRIPTION` — Append a structured entry. Options: `--type` (task/feature/fix/migration), `--author`, `--reqs` (comma-separated REQ IDs).
+- `list` — List ledger entries. Option: `--since YYYY-MM-DD`.
+- `stats` — Show entry count and per-author breakdown.
+
+## `specsmith req`
+
+Requirements management.
+
+```bash
+specsmith req list
+specsmith req add REQ-CLI-010 --component cli --priority high --description "Add export"
+specsmith req trace
+specsmith req gaps
+specsmith req orphans
+```
+
+**Subcommands:**
+
+- `list` — List all requirements with status, priority, and description.
+- `add REQ_ID` — Add a new requirement stub to `docs/REQUIREMENTS.md`.
+- `trace` — Show REQ → TEST traceability matrix (which tests cover each requirement).
+- `gaps` — List requirements that have no test coverage.
+- `orphans` — List tests that reference non-existent requirement IDs.
+
+## `specsmith plugin`
+
+List installed specsmith plugins.
+
+```bash
+specsmith plugin
+```
+
+Plugins extend project types and tool registries. They register via `pyproject.toml` entry points under `specsmith.types`. Shows each plugin's load status and any import errors.
+
+## `specsmith serve`
+
+Start the local API server for the web dashboard (placeholder).
+
+```bash
+specsmith serve --port 8910
+```
+
+Not yet fully implemented. See project roadmap for the planned REST API.
+
+## `specsmith credits limits`
+
+Manage persisted per-model RPM/TPM rate-limit profiles.
+
+```bash
+specsmith credits limits list
+specsmith credits limits set --provider openai --model gpt-4o --rpm 500 --tpm 30000000
+specsmith credits limits status --provider openai --model gpt-4o
+specsmith credits limits defaults
+specsmith credits limits defaults --install
+```
+
+**Subcommands:**
+
+- `list` — Print all locally saved profiles (provider, model, RPM, TPM, utilization target, concurrency).
+- `set` — Create or replace a local profile. Options: `--provider`, `--model`, `--rpm`, `--tpm`, `--target FLOAT` (default 0.70), `--concurrency INT` (default 1).
+- `status` — Show the rolling-window snapshot for a model: requests and tokens used in the current 60-second window, concurrency, moving averages.
+- `defaults` — List built-in profiles for common OpenAI, Anthropic, and Google models. Use `--install` to merge them into the local project config (existing overrides are preserved).
+
+Profiles are stored at `.specsmith/model-rate-limits.json` (gitignored). The scheduler uses these to pace requests before dispatch and to apply exponential backoff after a 429.
+
 ## `specsmith --version`
 
 ```bash

docs/site/governance.md

@@ -46,12 +46,12 @@ When AGENTS.md is kept small (~100-150 lines), governance details are delegated
 
 | File | Content | When Loaded |
 |------|---------|-------------|
-| `RULES.md` | Hard rules H1-H9, stop conditions | Every session start |
-|| `WORKFLOW.md` | Session lifecycle, proposal format, ledger format | Every session start |
-|| `ROLES.md` | Agent role boundaries, behavioral rules | Every session start |
-|| `CONTEXT-BUDGET.md` | Context management, credit optimization | Every session start |
-|| `VERIFICATION.md` | Verification standards, tools listing, acceptance criteria | When performing verification |
-|| `DRIFT-METRICS.md` | Drift detection, feedback loops, health signals | On audit or session start |
+| `RULES.md` | Hard rules H1-H11, stop conditions | Every session start |
+| `WORKFLOW.md` | Session lifecycle, proposal format, ledger format | Every session start |
+| `ROLES.md` | Agent role boundaries, behavioral rules | Every session start |
+| `CONTEXT-BUDGET.md` | Context management, credit optimization | Every session start |
+| `VERIFICATION.md` | Verification standards, tools listing, acceptance criteria | When performing verification |
+| `DRIFT-METRICS.md` | Drift detection, feedback loops, health signals | On audit or session start |
 
 This lazy-loading approach minimizes token consumption — agents only load VERIFICATION.md when they're actually running tests, not at every session start.
 
@@ -101,3 +101,19 @@ This is how context persists across sessions. When an agent starts with `resume`
 6. **Consistency** — Do AGENTS.md references resolve? Are requirement IDs unique?
 
 `specsmith audit --fix` auto-repairs what it can: creates missing stubs, compresses oversized ledgers, regenerates CI configs.
+
+## Hard Rules (H11 and H12)
+
+Two rules were added in v0.2.3 specifically for long-running agentic workflows:
+
+**H11 — No unbounded loops or blocking I/O without a deadline**
+
+Every loop or blocking wait in agent-written scripts and automation must have an explicit deadline or iteration cap, a fallback exit path when the deadline fires, and a diagnostic message on timeout. Violating patterns include `while True:` / `while ($true)` / `for (;;)` with no deadline guard, I/O polling loops with no deadline, and `sleep` inside a loop with no termination condition.
+
+`specsmith validate` enforces this by scanning `.sh`, `.cmd`, `.ps1`, and `.bash` files under `scripts/` and the project root for infinite-loop patterns without a recognised deadline/timeout guard.
+
+**H12 — Windows multi-step automation via .cmd files**
+
+On Windows, multi-step or heavily-quoted automation sequences must be written to a temporary `.cmd` file and executed from there. Inline multi-line quoting on Windows is fragile and causes avoidable hangs. Do not use `.ps1` files for this class of automation unless there is a concrete PowerShell-only requirement.
+
+See `docs/governance/RULES.md` in any governed project for the full set of H1–H12 rules and stop conditions.