Changed: update developer docs and optimize release tagging logic

Update AGENTS.md and scripts/README.md with details on feature flags,
code structure, and release workflows. Improve the efficiency of
changelog section extraction in tag_release.py by using slice-based
trimming.

Author: acgetchell

AGENTS.md

@@ -13,29 +13,36 @@ When making changes in this repo, prioritize (in order):
 ## Common commands
 
 - All tests (Rust + Python): `just test-all`
-- Changelog (generate full): `just changelog` (runs `git-cliff -o CHANGELOG.md`)
-- Changelog (prepend unreleased): `just changelog-unreleased v0.3.0`
-- Create release tag: `just tag v0.3.0` (creates annotated tag from CHANGELOG.md section)
 - Benchmarks: `cargo bench` (or `just bench`)
 - Build (debug): `cargo build` (or `just build`)
 - Build (release): `cargo build --release` (or `just build-release`)
-- CI simulation (lint + tests + examples + bench compile): `just ci`
+- Changelog (generate full): `just changelog` (runs `git-cliff -o CHANGELOG.md` + post-processing)
+- Changelog (prepend unreleased): `just changelog-unreleased v0.3.0`
 - Coverage (CI XML): `just coverage-ci`
 - Coverage (HTML): `just coverage`
+- Create release tag: `just tag v0.3.0` (creates annotated tag from CHANGELOG.md section)
 - Fast compile check (no binary produced): `cargo check` (or `just check-fast`)
 - Fast Rust tests (lib + doc): `just test`
 - Format: `cargo fmt` (or `just fmt`)
 - Integration tests: `just test-integration`
 - Lint (Clippy): `cargo clippy --all-targets --all-features -- -D warnings` (or `just clippy`)
 - Lint (Clippy, exact feature): `cargo clippy --features exact --all-targets -- -D warnings` (or `just clippy-exact`)
 - Lint/validate: `just check`
-- Pre-commit validation: `just ci`
+- Pre-commit validation / CI simulation: `just ci` (lint + tests + examples + bench compile)
+- Python setup: `uv sync --group dev` (or `just python-sync`)
 - Python tests: `just test-python`
 - Run a single test (by name filter): `cargo test solve_2x2_basic` (or the full path: `cargo test lu::tests::solve_2x2_basic`)
 - Run exact-feature tests: `cargo test --features exact --verbose` (or `just test-exact`)
-- Run examples: `just examples` (or `cargo run --example det_5x5` / `cargo run --example solve_5x5` / `cargo run --example const_det_4x4`)
+- Run examples: `just examples` (or `cargo run --example det_5x5` / `cargo run --example solve_5x5` /
+  `cargo run --example const_det_4x4` / `cargo run --features exact --example exact_sign_3x3`)
 - Spell check: `just spell-check` (uses `typos.toml` at repo root; add false positives to `[default.extend-words]`)
 
+## Feature flags
+
+- `exact` — enables `det_sign_exact()` (adaptive-precision determinant sign via `BigRational`).
+  Gates `src/exact.rs`, additional tests, and the `exact_sign_3x3` example.
+  Clippy, doc builds, and test commands have dedicated `--features exact` variants.
+
 ## Code structure (big picture)
 
 - This is a single Rust *library crate* (no `src/main.rs`). The crate root is `src/lib.rs`.
@@ -47,9 +54,17 @@ When making changes in this repo, prioritize (in order):
   - `src/ldlt.rs`: `Ldlt<const D: usize>` factorization without pivoting for symmetric SPD/PSD matrices (`solve_vec`, `det`)
   - `src/exact.rs`: `det_sign_exact()` — adaptive-precision determinant sign
     (Shewchuk-style f64 filter + Bareiss in `BigRational`); `features = ["exact"]`
-- A minimal `justfile` exists for common workflows (see `just --list`).
+- Rust tests are inline `#[cfg(test)]` modules in each `src/*.rs` file.
+- Python tests live in `scripts/tests/` and run via `just test-python` (`uv run pytest`).
 - The public API re-exports these items from `src/lib.rs`.
+- The `justfile` defines all dev workflows (see `just --list`).
 - Dev-only benchmarks live in `benches/vs_linalg.rs` (Criterion + nalgebra/faer comparison).
+- Python scripts under `scripts/`:
+  - `criterion_dim_plot.py`: benchmark plotting (CSV + SVG + README table update)
+  - `tag_release.py`: annotated tag creation from CHANGELOG.md sections
+  - `postprocess_changelog.py`: strips trailing blank lines from git-cliff output
+  - `subprocess_utils.py`: safe subprocess wrappers for git commands
+- Release workflow is documented in `docs/RELEASING.md`.
 
 ## Publishing note
 

scripts/README.md

@@ -118,3 +118,41 @@ gnuplot --version
 ```
 
 This repo has been tested with `gnuplot 6.0 patchlevel 3` (Homebrew `gnuplot 6.0.3`).
+
+## Changelog and release tooling
+
+### Generating the changelog
+
+```bash
+# Full regeneration from all history
+just changelog
+
+# Prepend only unreleased changes for a new version
+just changelog-unreleased v0.3.0
+```
+
+`just changelog` runs `git-cliff -o CHANGELOG.md` followed by
+`postprocess-changelog` (strips trailing blank lines). Configuration
+lives in `cliff.toml` at the repo root.
+
+### Creating a release tag
+
+```bash
+just tag v0.3.0          # create annotated tag from CHANGELOG.md section
+just tag-force v0.3.0    # recreate tag if it already exists
+```
+
+The `tag-release` CLI (in `tag_release.py`) extracts the matching version
+section from `CHANGELOG.md`, validates semver, and handles GitHub's 125KB
+tag-annotation size limit.
+
+### Scripts overview
+
+| Script | Purpose |
+|---|---|
+| `criterion_dim_plot.py` | Plot Criterion benchmark results (CSV + SVG + README table) |
+| `tag_release.py` | Create annotated git tags from CHANGELOG.md sections |
+| `postprocess_changelog.py` | Strip trailing blank lines from git-cliff output |
+| `subprocess_utils.py` | Safe subprocess wrappers for git commands |
+
+See `docs/RELEASING.md` for the full release workflow.

scripts/tag_release.py

@@ -115,11 +115,14 @@ def extract_changelog_section(changelog: Path, version: str) -> str:
         msg = f"No changelog section found for version {version}. Expected a heading like: ## [{version}] - YYYY-MM-DD"
         raise LookupError(msg)
 
-    # Trim leading/trailing blank lines
-    while section and not section[0].strip():
-        section.pop(0)
-    while section and not section[-1].strip():
-        section.pop()
+    # Trim leading/trailing blank lines (O(n) index scan + slice)
+    start = 0
+    while start < len(section) and not section[start].strip():
+        start += 1
+    end = len(section)
+    while end > start and not section[end - 1].strip():
+        end -= 1
+    section = section[start:end]
 
     body = "\n".join(section)
     if not body.strip():
@@ -137,9 +140,10 @@ def _tag_exists(tag_version: str) -> bool:
     """Return ``True`` if *tag_version* already exists as a git tag."""
     try:
         run_git_command(["rev-parse", "-q", "--verify", f"refs/tags/{tag_version}"])
-        return True
     except subprocess.CalledProcessError:
         return False
+    else:
+        return True
 
 
 def _delete_tag(tag_version: str) -> None: